HMAC Signature
Pronunciation: H-M-A-C SIG-nuh-cher
Definition
An HMAC signature is a shared-secret authentication tag calculated over defined message bytes using HMAC and an agreed cryptographic hash function.
Overview
Understand the idea
An HMAC signature lets two parties verify message integrity and possession of a shared secret. The sender computes a tag from the exact message and key, and the receiver independently computes the expected tag before accepting the message.
Although commonly called a signature, HMAC does not provide public verification or nonrepudiation because every verifier with the secret can generate valid tags. Security also fails if implementations sign different representations or omit important fields.
Systems should use strong unique secrets, approved hash functions, domain-separated message formats, timestamps or nonces, and constant-time comparison. Secret rotation needs overlapping key identifiers and controlled retirement so availability is maintained without accepting exposed keys indefinitely.
What actually happens
An HMAC is a message authentication code calculated using a secret key and a cryptographic hash. It allows two parties that share the secret to verify that a message was created by someone with that secret and was not changed. Payment webhooks and API requests may use HMAC signatures, but the exact header format, hashing algorithm and string-to-sign differ among providers.
The sender canonicalizes the intended bytes under an agreed format, then calculates an HMAC such as HMAC-SHA256 with the shared secret. The receiver independently computes the expected code from the exact received bytes and compares it in constant time. If the provider signs the raw HTTP body, JSON parsing and reserialization before verification can change whitespace and invalidate otherwise correct signatures. A timestamp within the signed material can support an expiry window against replay; it cannot replace durable event deduplication.
Decisions and failure cases
An HMAC is symmetric: both parties know the same secret. A leaked secret lets an attacker forge messages, so rotate it after compromise and use separate keys by environment. Do not compare signatures with ordinary string equality that can leak timing information; do not accept unsigned fallbacks on validation error.
Related concepts
Signature, Webhook Deduplication, Callback URL.
Further reading
Example
A merchant's webhook endpoint receives a JSON payment notification and an HMAC header. It reads the original request body, computes HMAC-SHA256 with its configured secret, checks the signature securely and only then processes the event. A changed invoice amount in transit would cause verification to fail if that field is covered by the signed bytes.
Comparison
HMAC checks authenticity/integrity under a shared secret. A public-key digital signature has a different trust model. TLS protects data in transit, while signature verification can authenticate a webhook payload as a separate layer.
Key Takeaway
An HMAC signature is a shared-secret authentication tag calculated over defined message bytes using HMAC and an agreed cryptographic hash function.
Sources
- NIST Documentation: Cryptographic Standards And Guidelines — NIST (2026-07-30)