Custom headers let you add your own HTTP headers to every request Haystack sends to a webhook. Use them to give the receiving system whatever extra information it expects alongside the data, such as an API key, a tag that says where the request came from, or a value that routes it to the right place.
Each webhook has its own set of custom headers, and they're sent with every request to that webhook, including test sends.
You can use custom headers for authentication, for example by sending an API key your endpoint checks. For the most secure option, we recommend a signing secret: see Verify webhook requests with HMAC signatures.
Before you start
Webhooks are available on paid Haystack plans.
You'll need to be a company admin with access to the Haystack Admin Dashboard.
You'll need a webhook already set up. If you don't have one yet, see Integrating Haystack with Your CRM Using Webhooks.
Add a header
A webhook without custom headers shows an Add header button under Custom headers:
In the Admin Dashboard, go to Integrations → Webhook.
On the webhook you want to change, find Custom headers and select Add header.
Enter the header name and its value.
Select Add.
Once saved, the header is listed under Custom headers with its value hidden as ••••••••. Haystack never shows a saved value again, so keep your own copy if you'll need it elsewhere.
Change a header
To change a value, click the hidden value, enter the new one, and select Save. The new value is used from the next request.
You can't edit a header's name. To rename a header, add it again under the new name, then remove the old one.
Remove a header
Select the bin icon next to the header, then confirm. Requests are sent without it from the next one on. Since the value can't be viewed, you'd need to re-enter it to add the header back.
Good to know
Values are sent exactly as you enter them. Haystack doesn't encode or reformat them.
Header names aren't case-sensitive, so
X-Sourceandx-sourceare the same header, and a webhook can only have one of them.You can add up to 10 custom headers per webhook.
A few names are reserved because Haystack sets them itself or because they control how the request is delivered, such as
Host,Content-TypeandContent-Length. If you try to use one, Haystack tells you why it can't be added.
Examples
Tag where requests come from
If one endpoint receives data from several sources, add a header such as X-Source: haystack so it can tell Haystack's requests apart.
Route requests on a shared endpoint
If several webhooks point at the same endpoint, give each one a different value for a header such as X-Region: emea or X-Team: sales. Your endpoint can then route or label each request without parsing its contents.
Choose an API version
Some APIs pick a version or response format from a header, such as Accept: application/vnd.example.v2+json or X-Api-Version: 2024-06-01. Add the header your API documents.
Send a credential your endpoint requires
Many APIs and gateways only accept requests that carry a key or token. Add it under the name they expect, for example:
Authorization: Bearer <your-token>for an API that accepts bearer tokensx-api-keyorOcp-Apim-Subscription-Keyfor an API gateway
Because saved values are never shown again, custom headers are a reasonable place for credentials like these. If you also want your endpoint to check that each request's contents came from Haystack unchanged, see Verify webhook requests with HMAC signatures.
Filter requests in Zapier, Make or n8n
Automation tools can check header values in a filter step. Add a header such as X-Haystack-Token with a long random value. Then add a filter straight after the webhook trigger that only continues when the header matches, so requests from anywhere else are ignored.
Troubleshooting
"… already exists — edit it above": the webhook already has a header with that name (names aren't case-sensitive). Change the existing header's value instead.
The header can't be added: the name is reserved, or the name or value contains characters a header can't use. The message under the field says which.
Your endpoint doesn't see the header, or rejects it: check the name is spelled the way your endpoint expects, then re-enter the value, since the saved one can't be viewed. Use Send test to try again.
Related articles
Integrating Haystack with Your CRM Using Webhooks: set up a webhook
Verify webhook requests with HMAC signatures: verify webhook requests with a signing secret