Set or remove custom headers
PATCH /v1/webhooks/{webhook_id}/headers
Read as Markdown ↗PATCH /v1/webhooks/{webhook_id}/headers
Requires an API key: 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
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
webhook_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
Request body
JSON object. Total UTF-8 request body limit: 4096 bytes.
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
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.
{
"set": {
"x-integration-token": "REPLACE_WITH_YOUR_VALUE"
},
"remove": [
"x-old-header"
]
}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.jsonResponses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"id": "11111111-1111-4111-8111-111111111111",
"header_names": []
}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.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
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.
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.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
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.
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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 · Download OpenAPI 3.1