> ## Documentation Index > Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt > Use this file to discover all available pages before exploring further. # Custom Headers for Webhooks > Attach static key-value headers to every Fireblocks webhook delivery so requests pass through your gateway, WAF, or API management layer. Your gateway, API management layer, or web application firewall (WAF) may require a fixed value on inbound requests before it routes them on, such as a routing tag, a tenant identifier, or a gateway key. Custom headers let Fireblocks send the values your infrastructure expects on every delivery, so Fireblocks traffic passes through the same front door as everything else you receive. Attach up to 10 static headers to a webhook. Fireblocks sends them on every delivery and every retry. Header values are static. For a credential that rotates on its own schedule, use [OAuth 2.0 for webhooks](https://developers.fireblocks.com/reference/webhooks-oauth.md). The two work together on the same webhook with one exception: `authorization` cannot be a custom header on a webhook that has an OAuth record attached, because Fireblocks sets that header itself from the record. A request that would leave a webhook with both is rejected. > [!NOTE] > > **Availability:** Custom headers for webhooks are available to Enterprise customers and above. Contact your Customer Success Manager to enable them for your workspace. ## Set headers Send a `customHeaders` object on [Create a new webhook](https://developers.fireblocks.com/api-reference/webhooks-v2/create-a-new-webhook.md): ```json theme={"system"} { "url": "https://webhooks.example.com/fireblocks", "customHeaders": { "X-Gateway-Key": "", "X-Region-Tag": "apac" } } ``` Both headers go out with every delivery for that webhook, including every retry attempt. ## Update headers [Update webhook](https://developers.fireblocks.com/api-reference/webhooks-v2/update-webhook.md) merges the `customHeaders` object you send with what's already configured, rather than replacing it: ```json theme={"system"} { "customHeaders": { "X-Gateway-Key": "", "X-Region-Tag": null } } ``` A key sent with a value is added, or updated if it already exists. A key sent as `null` is removed, and removing a key that isn't set doesn't return an error. Keys you don't mention are left untouched. To clear every header in one call, send `customHeaders` itself as `null`. `null` is valid only on update. On create there's nothing to remove yet, so the API rejects it. Validation applies to the set that would result from the update, not to the request alone, so a webhook that already has 9 headers rejects an update adding 2 new keys. If any header in a request fails validation, the whole request fails and nothing is changed. ## Repeat a header A value can be an array, and each entry goes out as its own header line: ```json theme={"system"} { "customHeaders": { "X-Route-Tag": ["payments", "eu"] } } ``` Your endpoint receives two `X-Route-Tag` lines. Each array counts as 1 header against the limit of 10, however many entries it has. `cookie` and `authorization` have no valid repeated form, so they accept only a single string. ## Read headers [Get webhook by ID](https://developers.fireblocks.com/api-reference/webhooks-v2/get-webhook-by-id.md) returns header names only, as an array: ```json theme={"system"} { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1d5e6b7a8c90", "url": "https://webhooks.example.com/fireblocks", "customHeaders": ["x-gateway-key", "x-region-tag"] } ``` Values are never returned. Header names are case-insensitive and stored lowercase, so `X-Gateway-Key` and `x-gateway-key` are the same header, and reads return them lowercased. Keep your own record of the values you set. ## Limits A webhook can have at most 10 headers, and the whole set must be under 16 KB when serialized. Individual values have no length limit of their own, so a single long value is fine as long as the set fits. Values can't contain control characters or line breaks, so a multi-line value such as a certificate has to be put on one line first, for example by base64-encoding it. The 16 KB limit is the Fireblocks limit, and your own receiver may accept less once you count the headers Fireblocks always sends. Check the header size limits on your web server or gateway before relying on large values. Fireblocks reserves these names for itself, and rejects them: `content-type`, `content-length`, `host`, `connection`, `transfer-encoding`, `user-agent`, `accept`, `accept-encoding`, `fireblocks-signature` and `fireblocks-webhook-signature`. See [Create a new webhook](https://developers.fireblocks.com/api-reference/webhooks-v2/create-a-new-webhook.md) for the header name rules. ## Security Header values are encrypted at rest, decrypted only at delivery, and never returned by the API or written to logs. Because values are static, treat them as long-lived credentials. Scope them narrowly at your gateway and rotate them on your own schedule by updating the webhook. ## Troubleshooting | Symptom | Likely cause | | - | - | | A create or update is rejected with `400` code `1400` naming a header | The name uses characters that aren't valid in an HTTP header name, or is longer than 128 characters | | A create or update is rejected with `400` code `1401` naming a value | The value contains a control character, or `cookie` or `authorization` was sent as an array | | A create or update is rejected with `400` code `1402` naming a header | The name is reserved by Fireblocks. Reserved names are listed on [Create a new webhook](https://developers.fireblocks.com/api-reference/webhooks-v2/create-a-new-webhook.md) | | An update adding headers is rejected with `400` code `1403` | The resulting set would exceed 10 headers or 16 KB. Remove keys with `null` in the same request | | A create is rejected with `400` code `1404` | A header was sent as `null`, which is valid only on update. Omit the key instead | | Custom headers are rejected with `400` code `1405` on every request | Custom headers aren't enabled for your workspace. Contact your Customer Success Manager | | Setting an `authorization` header is rejected with `400` code `1406` | The webhook has an OAuth record attached. Remove the header or detach the OAuth record, which one request can do together | | A header you set is missing at your endpoint | A later update sent it as `null`, or the name differs. Check [Get webhook by ID](https://developers.fireblocks.com/api-reference/webhooks-v2/get-webhook-by-id.md) for the current names | | Header names arrive lowercased | This is expected, because names are normalized. Match them case-insensitively at your endpoint | ## Related * [Advanced Webhook Controls](https://developers.fireblocks.com/reference/webhooks-advanced-controls.md) * [OAuth 2.0 for webhooks](https://developers.fireblocks.com/reference/webhooks-oauth.md) * [mTLS for webhooks](https://developers.fireblocks.com/reference/webhooks-mtls.md) * [Validating webhooks](https://developers.fireblocks.com/reference/validating-webhooks.md) * [Configuring webhooks](https://developers.fireblocks.com/reference/webhooks-gettingstarted-configuringwebhooks.md)