Encoding and security guides
HMAC webhook verification: sign the original request bytes
Keep the original payload, agree on encoding, and verify timestamps and replay controls alongside the MAC.
Use a keyed authenticator
HMAC combines a secret key with a cryptographic hash construction. A receiver with the same key can verify the agreed message bytes.
Do not invent a scheme by concatenating a secret and hashing it. Follow the provider’s documented algorithm and signed message structure.
Preserve the raw body
Parsing JSON and serializing it again can change whitespace, key order or escaping. That reconstructed body may produce a different MAC.
Capture the original request bytes before a framework’s body parser consumes them. Use those exact bytes when the provider signs the raw body.
{"id":1,"ok":true}
{"ok":true,"id":1}
Equivalent object values; different signed bytes.Agree on the output encoding
Hex and Base64 are different representations of the same MAC bytes. Confirm casing, prefixes and which fields are included in the signed input.
Use a synthetic key and message to compare implementations. The site’s generator output must be decoded or formatted to match the provider’s header specification.
Authentication is not replay prevention
A valid MAC does not establish that a request is fresh. Protocols often include a signed timestamp and a delivery identifier.
Verify with the backend library’s timing-safe comparison, enforce the documented time window, and deduplicate event identifiers before processing side effects.