Webhook Security and Signature Verification
Signature Verification
Every webhook delivery includes two headers for signature verification: X-Webhook-Signature-256 containing an HMAC-SHA256 signature of the raw request body, and X-Webhook-Timestamp containing the Unix timestamp when the payload was signed. Always verify both headers before processing the webhook payload.
Compute the expected signature by concatenating the timestamp and raw request body with a period separator, then calculating the HMAC-SHA256 using your webhook signing secret: expected = HMAC-SHA256(secret, timestamp + "." + rawBody). Compare the computed signature with the received signature using a constant-time comparison function to prevent timing attacks. In Node.js use crypto.timingSafeEqual(), in Python use hmac.compare_digest(), in Go use hmac.Equal().
Timestamp Validation and Replay Prevention
After verifying the signature, validate the timestamp to prevent replay attacks. Reject any webhook where the timestamp differs from the current time by more than 5 minutes (300 seconds). This window accounts for clock skew and network latency while preventing an attacker from replaying captured webhook payloads.
For additional replay protection, store the X-Webhook-ID header value from each processed webhook and reject duplicates. This idempotency check catches replays within the timestamp window and protects against webhook deliveries that are retried by our system due to network issues. Store processed IDs for at least 24 hours.
Secret Rotation
Rotate your webhook signing secret periodically or immediately if you suspect it has been compromised. The platform supports dual-secret mode during rotation: configure your new secret while keeping the old one active for a grace period. During the grace period, verify incoming webhooks against both secrets, accepting the payload if either signature matches.
To rotate secrets: call POST /webhooks/:id/rotate-secret to generate a new secret. The old secret remains valid for 24 hours. Update your webhook handler to verify against both secrets, deploy the change, then call DELETE /webhooks/:id/old-secret to deactivate the old secret. Never store webhook secrets in source code or client-side configuration.
Article metadata and referenced datasets are indexed by Google Scholar.