---
title: "Update Webhook"
method: PUT
path: "/webhooks/{webhookId}"
tags: ["Webhooks"]
---

# Update Webhook

`PUT /webhooks/{webhookId}`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/webhooks/{webhookId}`
- Auth: HTTP bearer

Update an existing webhook. Only the fields provided will be updated (partial update). You can change the name, target URL, authentication, events, or active status.

## Path parameters

- `webhookId` string, required

## Request body

- UpdateWebhookRequest: Request body for updating a webhook. Only provided fields will be updated. At least one of `name`, `url`, `auth_type`, `events` or `active` is required. Credentials are saved only together with `auth_type`: `basic` requires `auth_username` and `auth_password`; `oauth2` requires `oauth_client_id`, `oauth_client_secret` and `oauth_token_url`.
  - `name` string: Name of the webhook
  - `url` string, uri: URL where webhook events will be sent
  - `target` string, uri: Deprecated alias for `url`. Accepted for backwards compatibility.
  - `auth_type` 'none' | 'basic' | 'oauth2': Authentication type for the webhook
  - `auth_username` string: Username for basic authentication
  - `auth_password` string: Password for basic authentication
  - `oauth_token_url` string, uri: OAuth2 token URL
  - `oauth_client_id` string: OAuth2 client ID
  - `oauth_client_secret` string: OAuth2 client secret
  - `events` string[]: Event types that trigger the webhook. Fully-prefixed names such as `message.delivery` are canonical; short names (`delivery`) and the legacy `engagament.*` prefix are accepted for backwards compatibility and are normalised to the fully-prefixed form.
  - `active` boolean: Whether the webhook is enabled

## Response `200`

Webhook updated successfully

- ShowWebhookResponse: Response containing a single webhook
  - `message` string, required: Human-readable response message
  - `data` WebhookView, required: View of a webhook
    - `id` string, required: Unique identifier for the webhook
    - `name` string, required: Name of the webhook
    - `url` string, uri, required: URL where webhook events will be sent
    - `enabled` boolean, required: Whether the webhook is enabled
    - `event_types` string[], nullable: Specific event types the webhook receives (null if all events)
    - `auth_type` string, required: Authentication type for the webhook (none, basic, oauth2)
    - `has_auth_credentials` boolean, required: Whether authentication credentials are configured
    - `last_successful_at` string, date-time, nullable: Timestamp of the last successful webhook delivery
    - `last_failure_at` string, date-time, nullable: Timestamp of the last failed webhook delivery
    - `last_status` 'success' | 'failure' | 'null', nullable: Status of the last delivery attempt (success or failure)

## Other responses

- `400`: Bad request - Invalid webhook configuration
- `401`: Unauthorized - Missing or invalid API key
- `404`: Webhook not found
- `422`: Validation error
- `500`: Server error - Failed to update webhook
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

[API](https://skmtc.dev/lettr/apis/lettr-api.md) · [All operations](https://skmtc.dev/lettr/apis/lettr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lettr/apis/lettr-api/revisions/48ef0dac1ebd?raw)