Verify webhook signatures

Every webhook request is signed with the webhook’s own secret. Your receiver should check the signature and ignore anything that does not match.

The headers

Header	Value
X-Desk-Timestamp	When the request was signed, in Unix seconds
X-Desk-Signature	base64(HMAC-SHA256(secret, timestamp + "." + raw body))

Check a request

1. Read the raw request body, before any JSON parsing.
2. Compute HMAC-SHA256 of timestamp + "." + body with the secret, and base64-encode it.
3. Compare it with X-Desk-Signature in constant time.
4. Reject requests whose timestamp is more than 5 minutes old.

Code samples for Node, PHP and Python are on the developer webhooks page.

Find the secret

Open the webhook under Admin Center, Integrations, Webhooks. In Signing secret, choose Reveal.

Rotate the secret

Choose Rotate if the secret may have leaked. Requests are signed with the new secret immediately, so update your receiver at the same time, or it will reject them.

Make your receiver safe

• Answer with a 2xx status quickly, then do the work.
• Expect the same delivery more than once: retries and replays happen, so handle repeats safely.
• If your firewall needs it, allow ChaosDesk’s published outbound IP addresses.

Related

• Create a webhook
• Webhooks for developers