Skip to main content
Every delivery carries two headers: Three rules make verification correct:
  1. Compute the HMAC over the raw request body, not a re-serialised object. Re-serialising changes key order and whitespace, and the signature no longer matches.
  2. Compare in constant time. A byte-by-byte comparison that returns early leaks the expected value.
  3. Reject timestamps outside a small window. Five minutes is a reasonable default and it stops a captured delivery being replayed later.
A request that fails verification must be rejected. Never act on a webhook body whose signature you have not validated against that endpoint’s secret.

Verify the signature

Rotating the secret

POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret issues a new signing secret and returns it in full, once. Store the new value, then deploy the handler that uses it.

Test it end to end

POST /api/v1/webhook-endpoints/{endpoint_id}/test sends a webhook.test event through the same signed path as a real delivery, so it exercises your verification code exactly as production will.

Webhooks

Events, payload shape, deliveries, retries and replay.

Rotate the secret

The rotate-secret endpoint in the reference.