HMAC

Overview

HMAC produces a fixed-length authentication tag from three inputs: a message, a shared secret key, and a cryptographic hash function. It processes the key and message through a standardized inner-and-outer hashing construction. A verifier with the same secret repeats that calculation and compares the expected tag with the received tag. A match provides message integrity and shared-secret authenticity; it does not encrypt the message.

Successful verification requires both sides to sign exactly the same bytes. An API therefore needs a canonical representation of the HTTP method, path, timestamp, body, and any other covered fields. Differences in whitespace, character encoding, JSON serialization, or field order can produce different tags even when the data appears equivalent. This is why API authentication specifications must define the signing payload precisely.

Payment platforms commonly use a webhook signature based on HMAC. The sender signs the webhook payload, and the receiver calculates the tag with its stored secret before processing the event. The receiver should also validate a timestamp or nonce to prevent a valid signed message from being reused in a replay attack. Tag comparison must run in constant time so an attacker cannot infer the expected value from timing differences.

HMAC differs from a digital signature because it is symmetric: every party that can verify a tag can also create one. It therefore cannot prove which shared-key holder generated the message or provide public non-repudiation. It also does not protect confidentiality. If encryption is required, it must be applied separately. Key exposure allows an attacker to forge valid tags, so secrets need restricted access, rotation, and separation between environments and integrations.

For example, a merchant receiving a payment callback should retain the raw request body, reconstruct the documented signing string, calculate HMAC with the webhook secret, compare the complete tag in constant time, and only then update the order. Truncated comparisons, unsigned security-relevant fields, weak secrets, or accepting old timestamps can undermine an otherwise correct message authentication code.