# Edit a webhook PATCH /v1/webhooks/{webhook_id} Source: https://cherami.to/docs/api/webhooks/update-webhook {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `PATCH /v1/webhooks/{webhook_id}` Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. Edits the subscribed event types, inbox scoping and enabled state with absolute values. Omitted fields are unchanged; a supplied array replaces the whole list, and an empty `inbox_ids` array returns the webhook to every inbox. Scoped inbox IDs must be live inboxes of this account at the time of the change; `unknown_webhook_inbox` lists the rejected IDs in `error.details.inbox_ids`. `enabled: true` is the explicit re-enable after the provider disabled the webhook for persistent failures. Nothing re-enables automatically, and `enabled: false` stops new attempts without discarding the configuration. The URL cannot be edited: add a webhook and delete this one. A `409 webhook_operation_in_progress` means another change is in flight; retry after a minute. After `503 webhook_settings_uncertain`, read the webhook and apply the same values again; repeating absolute values is safe. ## Parameters [#parameters] | Parameter | Location | Required | Type | Meaning | | ------------ | -------- | -------- | ------ | ---------------------------------------------- | | `webhook_id` | path | Yes | string | Owned Cherami resource ID returned by the API. | ## Request body [#request-body] JSON object. Total UTF-8 request body limit: 4096 bytes. ### Schema: UpdateWebhook [#schema-updatewebhook] Absolute values; omitted fields are unchanged. Arrays replace the whole list. | Field | Required | Type | Meaning and constraints | | ------------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event_types` | No | array of [WebhookEventType](#schema-webhookeventtype) | `minItems`: `1` `maxItems`: `2` | | `inbox_ids` | No | array of string | Live inboxes this account owns, checked when the change is made. Empty or omitted means every inbox, including inboxes created later. `maxItems`: `10` | | `enabled` | No | boolean | true is the explicit re-enable after the provider disabled the webhook; nothing re-enables automatically. | Unknown fields are rejected. At least 1 field must be supplied. ## curl example [#curl-example] Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment. Save the intended payload as a private `request.json` file and replace illustrative values. For an uncertain response, follow the [operation-specific recovery rules](https://cherami.to/docs/api/errors#retry-by-operation). ```json { "event_types": [ "message.received", "message.sent" ], "enabled": true } ``` ```sh curl --silent --show-error --include --request PATCH \ "https://cherami.to/v1/webhooks/WEBHOOK_ID" \ --header "Authorization: Bearer $CHERAMI_API_KEY" \ --header 'Content-Type: application/json' \ --data-binary @request.json ``` ## Responses [#responses] ### HTTP 200 [#http-200] Successful operation; inspect resource state and outcome fields. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Webhook](#schema-webhook) ```json { "id": "55555555-5555-4555-8555-555555555555", "created_at": "2026-10-01T00:00:00.000Z", "url": "https://example.com/hooks/cherami", "event_types": [ "message.received" ], "inbox_ids": [ "11111111-1111-4111-8111-111111111111" ], "deleted_inbox_ids": [], "enabled": true, "updated_at": "2026-10-01T00:00:00.000Z", "status": "active", "pending_operation": null, "secret_rotated_at": null, "previous_secret_expires_at": null } ``` ### HTTP 400 [#http-400] `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_webhook_update`: Supply at least one of event\_types, inbox\_ids and enabled, with enabled as a boolean. `invalid_webhook_event_types`: Supply a nonempty array containing message.received and/or message.sent. `invalid_webhook_inbox_ids`: Supply inbox\_ids as an array of at most 10 inbox IDs, or an empty array for every inbox. `unknown_webhook_inbox`: Every inbox\_id must be a live inbox of this account. error.details.inbox\_ids lists the rejected IDs. `invalid_webhook_settings`: The webhook provider rejected the requested settings. Read the webhook and correct the values. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 401 [#http-401] `unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost. * `X-Request-ID`: Support correlation ID, not an idempotency key. * `WWW-Authenticate`: `"Bearer"` Content type: `application/json`. [Error](#schema-error) ### HTTP 404 [#http-404] `not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 409 [#http-409] `webhook_operation_in_progress`: Another change to this webhook is in flight. Retry after a minute; read the webhook first if an earlier change was uncertain. `webhook_endpoint_missing`: The webhook provider no longer has this endpoint. Delete the webhook and add it again; the ID is not reused. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 413 [#http-413] `body_too_large`: Reduce the JSON request to the endpoint's body limit. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 415 [#http-415] `unsupported_media_type`: Send `Content-Type: application/json`. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 503 [#http-503] `webhook_provider_unavailable`: The webhook provider refused or could not take the request and nothing was applied. Retry later. `webhook_settings_uncertain`: The provider did not confirm the settings change. Read the webhook; applying the same absolute values again is safe. `webhooks_unavailable`: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ## Schema: Webhook [#schema-webhook] status is the provider's live state: active delivers, disabled does not (set by you or by the provider after persistent failures), pending means creation or removal is unconfirmed, unknown means the provider could not be read or no longer has the endpoint. pending\_operation is distinct from status and names unconfirmed work. Secrets never appear here. | Field | Required | Type | Meaning and constraints | | ---------------------------- | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `created_at` | Yes | string | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `url` | Yes | string or null | | | `event_types` | Yes | array of [WebhookEventType](#schema-webhookeventtype) or null | | | `inbox_ids` | Yes | array of string or null | | | `deleted_inbox_ids` | Yes | array of string | Scoped inbox IDs that are no longer live inboxes. They match nothing; re-scope to remove them. | | `enabled` | Yes | boolean or null | | | `updated_at` | Yes | string or null | | | `status` | Yes | `"active"` or `"disabled"` or `"pending"` or `"unknown"` | | | `pending_operation` | Yes | object or null | | | `secret_rotated_at` | Yes | string or null | | | `previous_secret_expires_at` | Yes | string or null | | ## Schema: WebhookEventType [#schema-webhookeventtype] message.received: received mail became ready to read. message.sent: provider acceptance of a send was persisted; not delivery. `"message.received"` or `"message.sent"` ## Schema: Error [#schema-error] | Field | Required | Type | Meaning and constraints | | ------- | -------- | ------ | ----------------------- | | `error` | Yes | object | | ### `error` fields [#error-fields] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | --------------------------------------------------------------------------------------------- | | `code` | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. | | `message` | Yes | string | Human-readable context, not a stable string to match. | [HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) ยท [Download OpenAPI 3.1](https://cherami.to/openapi.json)