What is HMAC Signature?
Also called Request Signing, Webhook Signature.
An HMAC signature is a keyed hash computed over a request payload with a secret shared by sender and receiver, sent alongside the request so the receiver can recompute it and confirm the payload is authentic and unmodified. HMAC is defined in RFC 2104. It is the standard way providers let receivers verify that a webhook genuinely came from them.
The sender concatenates the parts it wants to protect, commonly a timestamp and the exact raw body, computes an HMAC using a hash function such as SHA-256 and the shared secret, and places the result in a header. The receiver repeats the computation with its copy of the secret and compares. A mismatch means the payload was altered or the sender did not hold the secret.
Two implementation details cause most real failures. The signature must be computed over the raw bytes received, not over a re-serialized parse of the JSON, because reordering keys or changing whitespace changes the hash. And the comparison must use a constant time function, since a naive equality check can leak the correct signature through timing differences.
A signature alone does not stop replay. Providers therefore include a timestamp inside the signed material and receivers reject anything outside a short tolerance window, often five minutes, so a captured request cannot be resent later. Recording processed event identifiers adds protection against replays within that window.
Rotation should be planned before it is needed. Providers commonly allow two active secrets and send multiple signatures during a rotation period so receivers can accept either. Endpoints that accept unsigned requests, or that verify only when a header happens to be present, offer no protection at all.
Key points
- Keyed hash over the payload using a shared secret
- Verify against the raw body, never a re-serialized copy
- Compare in constant time
- Sign a timestamp and reject stale requests
- Support two secrets to allow rotation
In practice
A payments provider posts an event and includes a header holding a timestamp and a SHA-256 HMAC over that timestamp joined with the raw body. The receiving endpoint reads the unparsed body, recomputes the value with its stored secret, compares in constant time, and rejects the request if the timestamp is older than five minutes. Only after verification does it parse the JSON and act.