What an HMAC signature actually proves
HMAC combines a cryptographic hash function such as SHA-256 with a secret key. The sender calculates a signature and the receiver repeats the calculation. Matching values show that the signed message has not changed in transit and came from a party that knows the shared secret. HMAC does not provide confidentiality, so TLS remains mandatory.
- Integrity of the signed data
- Authenticity of the sending system
- No encryption of the content
Sign one unambiguous message
Security depends on the exact string passed into the signature. The HTTP method, path, timestamp, nonce and a hash of the untouched request body should be combined in a precisely defined order. Both sides must use identical encoding, delimiters and normalisation. Webhook receivers should therefore validate the raw body before any JSON transformation.
- Bind the method and path
- Include a timestamp and nonce
- Sign a hash of the raw payload
Limit replay attacks
A valid signed request can be copied and sent again. A narrow time window limits its useful lifetime, while a unique nonce or event ID prevents repeated processing within that window. The receiver should first check the timestamp, reject IDs it has already seen and then validate the signature.
Verify without side channels or permissive fallbacks
Decode signatures and compare them with a constant-time function so timing differences do not leak useful information. Missing headers, unknown key IDs, stale timestamps and invalid encodings must all fail closed. Only after successful verification should the application process or permanently acknowledge the request.
- Use constant-time comparison
- Reject every verification failure
- Verify before business logic runs
Design for key rotation from day one
HMAC secrets belong in a secret manager, never in source code, logs or client applications. A key ID enables controlled rotation: the receiver accepts old and new keys for a short transition, then retires the old key decisively. Metrics for failed checks and replay attempts expose both attacks and integration defects early.
- Manage secrets server-side
- Prepare rotation with key IDs
- Monitor and alert on verification failures