D-16 · SECURITY · WEBHOOKS
Webhook security: signature verification
Unverified webhooks let anyone suppress your users or fake engagement. This scenario enforces signatures, timestamps, and rotation.
Symptom
A bounce webhook endpoint accepts unsigned POSTs. An attacker — or a misconfigured internal tool — fires fabricated “hard bounce” events for executive addresses, which auto-suppress. Transactional mail to those users silently stops, and the outage surfaces as “email is broken” with no failed sends in sight. Elsewhere, forged “opened” events inflate engagement metrics, masking a real placement collapse.
Even without malice, replayed legitimate events double-apply: a retried complaint webhook unsubscribes twice and corrupts audit counts, or a delayed bounce batch re-suppresses already-migrated addresses.
Cause
Vendors sign webhook payloads (HMAC over body plus timestamp, or asymmetric signatures) precisely so receivers can authenticate origin and freshness. Teams skip verification for speed — parsing JSON before checking headers — and accept any well-formed event. Missing timestamp validation admits replays indefinitely; hardcoded secrets without rotation turn one leak into permanent impersonation; verbose error responses leak whether an address exists.
Multi-vendor setups compound it: each provider’s scheme differs (header names, digest construction, clock skew tolerance), and a single generic handler verifies none correctly.
Fix
Verify before parsing: extract signature and timestamp headers, reject events outside a five-minute skew window, recompute the HMAC with the current secret over the exact raw body bytes, and compare in constant time. Process only verified events, keyed idempotently by event ID so replays are no-ops. Return generic 200s for invalid signatures without distinguishing reasons, and log rejected attempts with IP and payload hash for review.
Support secret rotation with dual-secret acceptance windows: accept old and new secrets during rollover, then retire the old. Store secrets in a manager, never in code, with per-vendor and per-environment separation.
Prevention
Cover every vendor handler with signature-fixture tests (valid, expired, tampered, wrong-secret) in CI, alert on rejection-rate spikes, and rotate secrets on personnel changes and at least annually. Restrict endpoint ingress where vendors publish source ranges, but never treat IP allowlisting as a substitute for signatures. Audit suppression audit trails quarterly: every entry must trace to a verified event ID.
Worked example
A SaaS bounce endpoint accepts unsigned events for “simplicity.” During a penetration test, researchers submit forged hard-bounce payloads for the CEO and support addresses; the system duly suppresses them, and invoice emails silently stop. The finding escalates from low-severity to business-critical in one meeting, because any user’s notifications can be disabled by anyone who guesses the endpoint.
The fix verifies HMAC signatures and five-minute timestamps before parsing, deduplicates by event ID, and rotates secrets into a manager with dual-acceptance rollover. Replayed and forged events now die at the edge with generic 200s while legitimate webhooks flow. Quarterly fixture tests — valid, expired, tampered, wrong-secret — keep every vendor handler honest, and the suppression audit trail traces each entry to a verified event.