Building webhook signatures that actually work in production

Webhook signatures should be boring. In practice, most CPaaS integrations get them subtly wrong — usually in ways that only bite you six months in, on an outage nobody can reproduce.

The four common mistakes

1. No timestamp — allows unbounded replay attacks
2. No secret rotation, or rotation with a hard cutover that drops in-flight deliveries
3. HMAC over the raw body but with server-side JSON re-encoding somewhere in the middle
4. Comparing signatures with `==` instead of a constant-time compare

How our signature is constructed

Header: X-CPaaS-Signature: t=1734567890,v1=abcd...

signed_payload = "{timestamp}.{raw_body}"
signature      = HMAC_SHA256(signing_secret, signed_payload)

On the receiver side you reject anything with a timestamp more than 5 minutes off, HMAC the concatenation yourself, and constant-time compare.

Rotation without dropped events

When you rotate a signing secret we keep the previous one accepted for 24 hours. That gives you a graceful window to redeploy your verifier code. Both secrets are returned by the API so you can log signature-verification success rate before you flip.

The best webhook signature scheme is one you can rotate at 2 AM without paging anyone.

— Every SRE, everywhere