Three rules make verification correct:
- 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.
- Compare in constant time. A byte-by-byte comparison that returns early leaks the expected value.
- Reject timestamps outside a small window. Five minutes is a reasonable default and it stops a captured delivery being replayed later.
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.