# Set or remove custom headers PATCH /v1/webhooks/{webhook_id}/headers Source: https://cherami.to/docs/api/webhooks/update-webhook-headers {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `PATCH /v1/webhooks/{webhook_id}/headers` Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. Sets and removes custom delivery headers in one request. Names are HTTP tokens and are lower-cased; a name cannot appear in both `set` and `remove`, and names the delivery provider manages (`svix-*`, `webhook-*`, `host`, `content-type`, `content-length`, `user-agent`) are refused. Values are printable strings of at most 1024 characters, delivered verbatim and never returned afterwards. Use a header to carry a shared token your receiver checks in addition to the signature, or routing metadata. After an uncertain response, repeating the same change is safe. `error.details.applied: true` on `webhook_headers_unavailable` means the change was made and only the name listing failed. ## 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: UpdateWebhookHeaders [#schema-updatewebhookheaders] Set and remove in one request; a name cannot be in both. Other headers are untouched. | Field | Required | Type | Meaning and constraints | | -------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `set` | No | object | Header name to value. Names are HTTP tokens, lower-cased; names the provider manages (svix-*, webhook-*, host, content-type, content-length, user-agent) are refused. | | `remove` | No | array of string | `maxItems`: `20` | 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 { "set": { "x-integration-token": "REPLACE_WITH_YOUR_VALUE" }, "remove": [ "x-old-header" ] } ``` ```sh curl --silent --show-error --include --request PATCH \ "https://cherami.to/v1/webhooks/WEBHOOK_ID/headers" \ --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`. [WebhookHeaders](#schema-webhookheaders) ```json { "id": "11111111-1111-4111-8111-111111111111", "header_names": [] } ``` ### HTTP 400 [#http-400] `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_webhook_headers`: Correct header names (HTTP tokens, provider-managed names excluded), values (printable, at most 1024 characters) or the set/remove shape; at most 20 of each per request. * `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_headers_uncertain`: The provider did not confirm the header change. List the header names; applying the same change again is safe. `webhook_headers_unavailable`: Header names could not be read. If error.details.applied is true the change was made; list the headers again. `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: WebhookHeaders [#schema-webhookheaders] | Field | Required | Type | Meaning and constraints | | -------------- | -------- | --------------- | ------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. | | `header_names` | Yes | array of string | | ## 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)