Skip to main content
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. 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.
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:
Both headers go out with every delivery for that webhook, including every retry attempt.

​
Update headers

Update webhook merges the customHeaders object you send with what’s already configured, rather than replacing it:
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:
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 returns header names only, as an array:
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 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