---
title: "Set or remove custom headers"
method: PATCH
path: "/v1/webhooks/{webhook_id}/headers"
tags: ["webhooks"]
---

# Set or remove custom headers

`PATCH /v1/webhooks/{webhook_id}/headers`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/webhooks/{webhook_id}/headers`
- Auth: HTTP bearer

Sets and removes custom headers sent with every delivery, in one request; headers you don't name stay as they are. Values are sent as written and never shown again. Use a header for a shared token your receiver checks alongside the signature, or for routing. Repeating the same change is safe.

## Path parameters

- `webhook_id` string, required

## Request body

- UpdateWebhookHeaders: Set and remove in one request; a name can't be in both. Other headers stay as they are.
  - `set` object: Header name to value. Names are HTTP tokens, stored in lowercase; reserved names (svix-*, webhook-*, host, content-type, content-length, user-agent) are refused.
  - `remove` string[]

## Response `200`

Success.

- WebhookHeaders
  - `id` string, required: Cherami resource ID.
  - `header_names` string[], required

## Other responses

- `400`: `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_webhook_headers`: Correct the header change the message names. Names are HTTP tokens of at most 128 characters, other than `Host`, `Content-Type`, `Content-Length`, `User-Agent` and names starting `svix-` or `webhook-`; values are printable and at most 1024 characters; `set` and `remove` take at most 20 entries each.
- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `404`: `not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
- `409`: `webhook_operation_in_progress`: Another change to this webhook is in progress. Retry in a minute. `webhook_endpoint_missing`: This webhook no longer receives events and cannot be changed. Delete it and add it again; the new webhook has a new ID and signing secret.
- `413`: `body_too_large`: Reduce the JSON request to the operation's body limit.
- `415`: `unsupported_media_type`: Send `Content-Type: application/json`.
- `503`: `webhook_provider_unavailable`: The request could not be completed, and nothing changed. Retry later. `webhook_headers_uncertain`: The header change was not confirmed. Apply the same change again; repeating it is safe. `webhook_headers_unavailable`: Header names could not be read. When `error.details.applied` is true the change was made; list the headers again. `webhooks_unavailable`: Webhook management failed. If it was a change, it may have been applied: list or read the webhooks before repeating it.

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)