The Webhook Security Contract

Follow the trust boundary: the consumer's receiver must be reachable from the public internet (the provider calls it from their infrastructure), so *anyone* can POST to it. If the handler trusts the body, the attack is one curl: forge {"type":"payment.succeeded","data":{"order_id":"ord_mine"}} at a store's webhook URL and walk away with unpaid goods. The endpoint URL is not a secret — it leaks through logs, referrers, browser history and misconfigured monitoring — and defenses built on hiding it are defenses built on nothing.

The non-solutions are worth naming because each ships constantly. A static token in the URL (?token=abc123) is a password logged by every proxy on the path. Source-IP allowlists break when the provider moves infrastructure and provide nothing against an attacker in the same cloud; they are defense-in-depth at best. TLS proves the *consumer's* identity to the provider and encrypts the channel — it does nothing to prove to the consumer who sent the request. The channel being private says nothing about who is on the other end of it; that boundary reasoning is the Trust Boundaries discipline applied to an inbound edge you were not thinking of as one.

The standard scheme: provider and consumer share a per-endpoint secret; each delivery carries a header with a timestamp and HMAC-SHA256(secret, timestamp + "." + raw_body). The consumer recomputes and compares. A valid MAC proves two things at once — the sender holds the secret (authenticity) and the body is byte-identical to what was signed (integrity). The timestamp inside the signed string is what stops replay: an attacker who captures a legitimate delivery cannot re-send it next week, because the aged timestamp fails the tolerance check, and cannot freshen the timestamp, because that breaks the MAC.

The implementation traps are boringly consistent. Verify over the raw request bytes, not a re-serialized parse — JSON parsers reorder keys and normalize whitespace, and any byte difference is a false rejection (or worse, teams "fix" it by disabling verification). Compare with a constant-time function, not ==, or the comparison's timing leaks the MAC byte by byte. Enforce the timestamp window *and* keep Consumer-Side Idempotency's event-id dedup: the window shrinks the replay surface to minutes, dedup closes it — a replayed event inside the window is a duplicate event_id and drops at the gate.

Secrets leak — into a git repo, a log line, a departed contractor's laptop — so rotation must be routine, and routine rotation requires overlap. The provider signs with the new secret while the consumer accepts both old and new for a bounded window (verify against each active secret; some providers send multiple v1= values in one header). Rotation without overlap is a synchronized deploy across two organizations, which means in practice it never happens and three-year-old secrets accumulate. The contract should state who initiates rotation, how long both secrets stay valid, and that per-endpoint secrets keep one leak from compromising every consumer.

Two operational clauses finish the contract. First: verify before anything else — before parsing, before dedup lookups, before logging the body — so forged traffic costs one HMAC and cannot probe your handler's behavior. Second: signature verification failures deserve their own metric and alert; a spike is either an attack, a consumer's broken deploy, or a botched rotation, and all three want a human. The cryptographic background — why HMAC rather than a bare hash, what MACs do and do not prove — is Security Engineering's ground; the contract's job is choosing the clauses and making them verifiable by every consumer, forever.