Verifying webhook signatures correctly

A webhook endpoint has to be reachable from the public internet — that's the entire point, it's how a third-party gateway calls it. Without verifying the request actually came from the gateway, that same public reachability means anyone who discovers the URL could POST a fabricated "transaction succeeded" payload and have a system believe an order was paid for when it wasn't. Signature verification is what closes that gap.

If both sides used the same secret and hashed the same bytes, the signatures match — and since HMAC is a keyed hash, only someone who knows the shared secret (a merchant, and the gateway) could have produced a matching signature. This is symmetric-key authentication, not encryption — the payload itself is often still plain, readable JSON; the signature only proves who sent it, not that it's hidden from anyone reading network traffic.

It's tempting to assume the signature always covers "the JSON body, verbatim." In practice, different gateways — and even different event types from the same gateway — can compute the signature over different things:

The only way to get this right is reading that specific gateway's documentation for that specific event type — assuming "it's always the raw body" is a common, and completely reasonable-looking, mistake that produces a verification function that silently never matches.

A naive string comparison (===, or most languages' default equality) returns as soon as it finds the first mismatched character — which means the time it takes to fail leaks information about how many leading characters were correct. Given enough attempts, that timing difference is (in principle) enough to reconstruct a valid signature byte by byte. timingSafeEqual-style functions take the same amount of time regardless of where the mismatch is, closing that channel. The length check has to happen before the constant-time comparison, since most timingSafeEqual implementations throw (or behave undefined) on mismatched-length buffers rather than safely returning false.

The verification step belongs as the very first thing an endpoint does — commonly implemented as a guard/middleware that runs ahead of any handler logic — precisely so an invalid signature is rejected before the payload is ever parsed into a domain object, looked up in a database, or acted on in any way.