APIintermediate

Webhook Signature Verification

Cryptographic signing of webhook payloads using HMAC-SHA256 so consumers can verify authenticity and integrity of incoming events.

Also known as: Webhook HMAC Verification, Payload Signing

Description

Webhook signature verification protects consumers from accepting forged or tampered webhook payloads. The webhook producer computes an HMAC-SHA256 hash of the raw request body using a shared secret known only to the producer and consumer, then includes this signature in a request header. The consumer recomputes the HMAC using the same secret and raw body, and compares it against the header value using a timing-safe comparison function to prevent timing attacks.

The signing scheme should include a timestamp to prevent replay attacks. A common format is to prepend the Unix timestamp to the payload before hashing: HMAC-SHA256(secret, timestamp + '.' + body). The consumer verifies both the signature and that the timestamp is within an acceptable window (typically 5 minutes). The signature header typically encodes both the timestamp and signature: Webhook-Signature: t=1614556800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd.

The shared secret should be unique per webhook endpoint (not a global secret), generated with sufficient entropy, and rotatable without downtime. During rotation, the system can sign with both old and new secrets simultaneously (sending multiple signatures in the header) until the consumer confirms they've updated to the new secret. Verification libraries should be provided in popular languages to reduce integration friction.

Prompt Snippet

Sign webhook payloads by computing HMAC-SHA256 over timestamp.payload using a per-endpoint 256-bit secret generated via crypto.randomBytes(32). Include the header as Webhook-Signature: t={unix_epoch},v1={hex_signature}. Consumer verification must use crypto.timingSafeEqual() to prevent timing side-channel attacks and reject payloads where abs(now - timestamp) > 300 seconds. During secret rotation, sign with both old and new secrets (v1=...,v1=...) for a 72-hour overlap window. Publish verification code snippets for Node.js, Python, Ruby, and Go in the webhook documentation.