HMAC webhook security: signatures done properly

A webhook endpoint is an unauthenticated URL that changes state in your system. Read that sentence again as an attacker would. Anyone who learns the URL (from a log, a browser history, a misconfigured proxy, or plain guessing) can POST whatever they like at it. If your handler processes 'payment received' or 'email arrived' events on trust, an attacker can manufacture those events at will.

Obscure URLs are not a defence; URLs leak. IP allowlists are brittle and don't survive the sender's infrastructure changes. The standard answer is a shared-secret signature: the sender computes an HMAC over each request, the receiver recomputes it, and a request that doesn't carry a valid signature is discarded before it touches any business logic. Simple in principle, and yet most real-world verification code gets at least one of four details wrong. Let's take them in order.

An HMAC is computed over an exact byte sequence. The single most common verification bug is computing it over something that merely resembles the request: parsing the JSON and re-serialising it, trimming whitespace, or letting a framework middleware decode the body before you can read it. Re-serialised JSON is not the same bytes (key order, spacing, and unicode escaping all differ), so the signature fails intermittently and someone eventually 'fixes' it by disabling verification. That story ends badly.

The rule: capture the raw request body as bytes, verify the signature against those bytes, and only then parse. In Express that means express.raw() on the webhook route; in most frameworks it means reading the body stream before any JSON middleware touches it.

A valid signature proves who sent a request, not when. Without more, an attacker who captures one legitimate signed request (from a log file, a compromised proxy, a packet capture) can replay it a thousand times, and every copy verifies perfectly. If the event is 'top up account' or 'email arrived, trigger workflow', replays are free ammunition.

The fix is to make time part of the signed material. The sender includes a timestamp header and computes the HMAC over the timestamp concatenated with the body. The receiver rejects any request whose timestamp is outside a tolerance window. Five minutes is the conventional choice, generous enough for clock skew and retry delays, tight enough that a captured request goes stale quickly. Reject the stale request before comparing signatures; there's no reason to spend crypto cycles on it. For state-changing events, pair the window with idempotency keys so even a fast replay inside the window can't double-apply.

The natural way to compare two signatures (a string equality check) leaks information. Naive comparisons return the moment they find a differing byte, so a forged signature that gets the first byte right takes measurably longer to reject than one that doesn't. Given enough requests and careful timing, an attacker can grind out a valid signature byte by byte. It's a niche attack, but the defence is one line, so there's no excuse.

Every serious crypto library ships a constant-time comparison: crypto.timingSafeEqual in Node, hmac.compare_digest in Python, hash_equals in PHP. Use it, and compare same-length buffers (timingSafeEqual throws on length mismatch, so check length first and fail closed).

Here is all of the above in one Node handler, with raw body, timestamp window and constant-time compare:

Secrets have lifetimes. An engineer leaves, a laptop is lost, a secret lands in a log, and now you need to change the key without dropping legitimate traffic in the gap between sender and receiver updating. The naive approach (change it on both ends and hope) guarantees a window of failed deliveries.

The robust pattern is overlapping validity: the receiver accepts signatures from either the current or the previous key for a bounded grace period. The sender switches to the new key; requests signed with the old one keep verifying until the grace period ends; then the old key is retired. Some providers make this even smoother by sending multiple signatures (one per active key) in a single header, so the receiver just needs any one to match.

Verification is your half of the contract; the sender owes you the other half. A provider worth trusting signs every delivery with a documented scheme, includes a timestamp in the signed material, publishes exactly what bytes are signed and in what order, supports per-endpoint secrets, and offers a rotation path that doesn't drop traffic. If the documentation can't answer 'what exact string do I feed the HMAC?', you'll be reverse-engineering it from failing requests.

That checklist is worth applying to anything that POSTs into your systems: payment processors, CI systems, and email pipelines alike. When HideMy.world delivers a parsed email to your webhook, every request is signed along these lines so your handler can verify it with precisely the code above. Whoever the sender is, the discipline is the same: authenticate the bytes, bound the time, compare in constant time, and rotate without downtime. Four details, one afternoon, and your public door has an actual lock.