HMAC signature
An HMAC signature is a keyed hash of the exact request body that lets the receiver prove the message came from the holder of the shared secret and was not modified in transit.
The sender hashes the raw request body with a shared secret using SHA-256 and puts the result in a header. The receiver repeats the computation with its own copy of the secret and compares the two values in constant time. A mismatch means the request is forged, corrupted or replayed with a different payload.
The most common integration bug is hashing a re-serialised body. Parsing JSON and stringifying it again can change key order, spacing or number formatting, so the hash no longer matches. Always capture the raw bytes before any parsing, and only then verify.
- Hash the raw body bytes, never a re-serialised object
- Compare in constant time to avoid timing leaks
- Rotate the shared secret if it is ever exposed
- Reject unsigned or mis-signed requests before processing
Frequently asked questions
Why does my signature check fail even though the payload looks identical?
Almost always because the body was parsed and re-serialised before hashing. Capture and hash the raw request bytes.
Is HTTPS not enough on its own?
HTTPS protects the channel but does not prove who sent the request. HMAC authenticates the sender and the exact payload.