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

HeaderContent
X-Crm-EventThe event type, e.g. record.created, webhook.test or automation.step
X-Crm-TimestampWhen the request was signed, in Unix time (seconds)
X-Crm-SignatureLowercase hex HMAC-SHA256(secret, timestamp + "." + rawBody)
X-Crm-Delivery-IdThe same on every attempt of one delivery (and of one automation step), so you can skip a repeat
Content-Typeapplication/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

  1. 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.
  2. Take the X-Crm-Timestamp header as it is (a string of digits).
  3. Join them: timestamp + "." + rawBody.
  4. Compute HMAC-SHA256 of that with your secret (the whole string, including whsec_) and write it as lowercase hex.
  5. Compare it with X-Crm-Signature in 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.
  6. 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
Secretwhsec_5f0c1d2e3a4b5c6d7e8f90a1b2c3d4e5f6a7b8c9d0e1f2a3
X-Crm-Timestamp1762941600
X-Crm-Signature80d212b9b257701c20f715e3ded11d89870e8f0c05c300034deadb0e22d8ca5b

The body, exactly as sent (one line, with a space after each : and ,):

JSON
{"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 byWhen your server doesn't answer with 2xx
An endpoint deliveryUp 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 testNever retried. The result shows on the button, and the test is kept in the delivery log.
The Call webhook stepTried 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.