HMAC-SHA256 API Signing: Sign Requests

What HMAC actually is

HMAC (Hash-based Message Authentication Code) is a keyed hash. It takes a secret and a message and produces a fixed-size signature that depends on both.

Because the secret is mixed into the computation, only someone who knows the secret can produce or verify the signature. That makes HMAC the workhorse of API authentication, webhook verification, and signed payloads.

HMAC is not encryption: the signature hides nothing, and anyone who captures a signed request can still read the message. HMAC proves authentication and integrity — that the message came from someone holding the secret and was not altered.

When you need HMAC signatures

The most common cases are webhooks and API requests. When a provider posts an event to your endpoint, the signature confirms the payload is genuine before you act on it. When a client calls your API, a signed request proves the caller holds the secret without sending it.

• Webhooks: the receiver verifies the signature to prove the payload came from the sender
• API authentication: clients sign requests with a shared secret instead of sending a password
• Integrity checks: detect message tampering between services
• Replay protection: sign a message that includes a timestamp or nonce

Create an HMAC-SHA256 signature: step by step

Canonicalization is where integrations usually break. When I first set up webhook verification, every signature failed because the sender added a trailing newline my side did not expect. The fix was agreeing on the exact bytes: the receiver must rebuild the exact string you signed, with the same JSON key order, escaping, and line endings.

// Example: canonical string and HMAC-SHA256 in Node.js
const canonical = [method, path, timestamp, body].join('\n');
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

1. Open the HMAC Generator in your browser.
2. Select SHA-256 as the algorithm.
3. Paste your secret key into the key field. Generate one with the Password Generator if needed.
4. Paste the exact message or payload you want to sign, byte for byte.
5. Copy the generated signature and attach it to the request, for example as an Authorization or X-Signature header.

Verify signatures safely on the receiving side

Verification is a second HMAC computation with the same secret and message, compared against the received signature.

The comparison must be constant-time. A plain string comparison can leak timing information that helps attackers forge signatures.

A plain comparison stops at the first differing character, so response time reveals how close the attacker's guess is. Enough samples recover the signature byte by byte, while a constant-time comparison always runs the same operations.

// Node.js: constant-time comparison
const crypto = require('crypto');
const expected = Buffer.from(signature, 'hex');
const received = Buffer.from(given, 'hex');
const valid = expected.length === received.length && crypto.timingSafeEqual(expected, received);

Common HMAC mistakes

• Hard-coding the secret in client-side code where everyone can read it
• Signing the body but not the method, path, and timestamp, enabling replay attacks
• Using == or plain string comparison for signature verification
• Reusing the same secret across environments or never rotating it
• Feeding the signature into a tool that logs the secret alongside the message
• Building the canonical string differently from the receiver, like different JSON key order or trailing whitespace
• Comparing signature bytes in different encodings, such as hex on one side and base64 on the other

FAQ

References

• RFC 2104 – HMAC: Keyed-Hashing for Message Authentication: https://www.rfc-editor.org/rfc/rfc2104
• NIST FIPS 198-1 – The Keyed-Hash Message Authentication Code (HMAC): https://csrc.nist.gov/pubs/fips/198-1/final
• RFC 7515 – JSON Web Signature (JWS): https://www.rfc-editor.org/rfc/rfc7515
• OWASP Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html