Check a webhook's signature
Every request the CRM sends to a webhook is signed: deliveries to endpoints under Settings → Webhooks, the Send a test button there, and the Call webhook step in automations. Check the signature before you trust the request. It proves the request came from your organisation in the CRM and that nobody changed the body on the way.
The headers
| Header | Content |
|---|---|
X-Crm-Event | The event type, e.g. record.created, webhook.test or automation.step |
X-Crm-Timestamp | When the request was signed, in Unix time (seconds) |
X-Crm-Signature | Lowercase hex HMAC-SHA256(secret, timestamp + "." + rawBody) |
X-Crm-Delivery-Id | The same on every attempt of one delivery (and of one automation step), so you can skip a repeat |
Content-Type | application/json |
The secret depends on who sent the request:
- Endpoint deliveries and Send a test use the endpoint's own secret, shown once when you create the endpoint or rotate its secret.
- The Call webhook step uses your organisation's automation webhook secret. It is made the first time a step calls out, and you rotate it (and see the new one, once) under Settings → Webhooks → Automation webhook secret.
Step by step
- Read the raw request body as bytes, before any JSON parsing. Parsing and printing the JSON again changes spaces and key order, and the signature no longer matches.
- Take the
X-Crm-Timestampheader as it is (a string of digits). - Join them:
timestamp + "." + rawBody. - Compute HMAC-SHA256 of that with your secret (the whole string, including
whsec_) and write it as lowercase hex. - Compare it with
X-Crm-Signaturein constant time. A normal string compare stops at the first different character, and the time it takes tells an attacker how much of a guess was right. - Reject the request if the timestamp is more than 5 minutes away from your clock. Someone who records a signed request can't send it to you again later.
Answer with a 2xx status within 10 seconds, and do slow work after you've answered.
A worked example
Check your code with these values before you go live. With this secret, timestamp and body, your code must produce the signature below.
| Value | |
|---|---|
| Secret | whsec_5f0c1d2e3a4b5c6d7e8f90a1b2c3d4e5f6a7b8c9d0e1f2a3 |
X-Crm-Timestamp | 1762941600 |
X-Crm-Signature | 80d212b9b257701c20f715e3ded11d89870e8f0c05c300034deadb0e22d8ca5b |
The body, exactly as sent (one line, with a space after each : and ,):
{"id": "3f1c2a9e-6b7d-4e21-9a0b-5c8d7e6f1a2b", "data": {"recordId": "5b1c2f6e-8d3a-4c1e-9f0b-2a7d6e4c8b19", "objectKey": "contact"}, "event": "record.created", "version": 1, "occurredAt": "2025-11-12T10:00:00Z"}
The timestamp in the example is old, so leave out the 5-minute check while you test with it.
Code
Each sample takes the raw body, the two headers and the secret, and returns true only for a valid, fresh request.
// Node.js. With Express, read the raw body: app.post('/hook', express.raw({ type: 'application/json' }), …)const crypto = require('node:crypto')function verifyCrmWebhook(rawBody, timestamp, signature, secret) {if (!/^\d+$/.test(timestamp ?? '') || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {return false}const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex')const given = Buffer.from(signature ?? '', 'utf8')return given.length === expected.length&& crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given)}// in the handler: verifyCrmWebhook(req.body, req.get('X-Crm-Timestamp'), req.get('X-Crm-Signature'), secret)
Rotating a secret
Rotate a secret when it may have leaked, or when someone who knew it leaves. The new secret is shown once and takes over at once: requests signed after the rotation no longer verify with the old one, and a delivery waiting for a retry is signed again with the new one when it goes out. To switch without missing anything, update the secret in your code right after you rotate, or accept both for a few minutes while you deploy.
Retries and duplicates
| Sent by | When your server doesn't answer with 2xx |
|---|---|
| An endpoint delivery | Up to 8 tries in all: the second 30 seconds after the first, then twice as long between each. After the last try it is marked dead in the endpoint's delivery log, where you can send it again. |
| Send a test | Never retried. The result shows on the button, and the test is kept in the delivery log. |
| The Call webhook step | Tried again every 5 minutes for an hour, then the run fails. A 4xx answer other than 408 and 429 fails the run straight away, because trying again won't help. |
A request can arrive more than once (for example when your server took the request but the answer was lost). Each body has an id that stays the same on every retry: keep the ids you've handled and skip a repeat.
Redirects aren't followed: give the final address. The CRM only calls public addresses over http or https, never private networks.