HMAC Generator for Signature Verification Debugging
Use an HMAC generator to debug webhook and API signatures by checking secret selection, raw payload bytes, canonical strings, hash algorithms, timestamp prefixes, Base64 or hex encoding, and safe comparison order.
HMAC signature failures are frustrating because the error message is usually short: signature mismatch, invalid webhook, unauthorized callback. The real cause may be the wrong secret, modified payload bytes, a different hash algorithm, a timestamp prefix, or a hex/Base64 encoding mismatch.
Start with the exact bytes being signed
Before using an HMAC Generator, capture the exact raw payload that the sender signed. This is not always the parsed JSON object. Pretty-printing JSON, changing whitespace, normalizing Unicode, or reserializing fields in a different order can change the bytes and therefore the signature.
For webhook handlers, keep the raw request body before middleware parses it. For API clients, log a safe representation of the canonical string: method, path, query string, timestamp, body hash, or whatever the provider documents. Do not rebuild the signed input from memory.
Confirm secret and algorithm separately
Debug in layers. First confirm the secret: environment, account, endpoint, and rotation date. Many systems have separate secrets for sandbox, production, workspace, and webhook endpoint. Then confirm the algorithm: HMAC-SHA256 is common, but providers may use SHA1, SHA384, SHA512, or a custom canonical string.
If you only change both secret and algorithm at once, you cannot know which one fixed the mismatch. Generate one candidate signature at a time and compare it with the received signature.
Match the output encoding
The same HMAC bytes can be represented as hex, Base64, or Base64URL. If the provider sends a header such as `sha256=<hex>`, compare against hex. If it sends a Base64 string, compare against Base64. Use Base64 Encoder only for encoding or decoding representation, not as a replacement for HMAC.
If you need a plain digest without a secret, use Hash Generator. HMAC and hash are related but not interchangeable: HMAC uses a secret key to authenticate the message.
Build a repeatable verification order
A reliable debugging order is:
- Capture the raw payload or canonical string.
- Select the exact secret for the environment and endpoint.
- Select the documented HMAC algorithm.
- Generate the signature using the raw input.
- Encode the result in the provider's expected representation.
- Compare against the received header after removing prefixes.
- Only then inspect timestamp tolerance, replay protection, and header parsing.
This sequence prevents random fixes. If the generated signature matches locally but your application still rejects it, the bug is likely in header extraction, prefix handling, timestamp parsing, or constant-time comparison code.
FAQ
Is HMAC the same as a hash?
No. A hash digests data without a secret. HMAC combines a secret key with a hash function to authenticate the message.
Why does formatting JSON break webhook verification?
The signature is calculated from bytes. Changing whitespace, field order, or escaping changes the bytes even if the JSON value looks equivalent.
Should I compare hex and Base64 strings directly?
No. They are different representations of bytes. Match the provider's expected encoding before comparing.
Can I share webhook payloads while debugging?
Only after redacting secrets and customer data. Keep the byte shape only when it is required to reproduce the signature issue.