HMAC Generator

The #1 Mistake When Verifying Webhook Signatures

When building a server to receive webhook notifications, like for a completed payment, you must verify the signature. If you don't, anyone can fake a "payment successful" request and get your product for free. But when you first write the verification code, the signature will almost certainly mismatch. The cause is almost always the same: you're re-serializing a parsed object to generate the signature.

The sender signs the exact body bytes they are transmitting. If the receiver parses the body into a JSON object and then re-serializes it back to a string, subtle differences in whitespace, line breaks, key order, or character escaping will appear. If even one byte is different, the HMAC will be completely different. You must always use the raw body bytes for verification.

// Express: This route must receive the raw body (place before global express.json())
app.post("/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.get("X-Signature") || "";
    const mine = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET)
      .update(req.body)          // The raw Buffer. Do not parse and then re-serialize.
      .digest("hex");

    const a = Buffer.from(sig, "utf8");
    const b = Buffer.from(mine, "utf8");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));  // Parse only after successful verification.
    res.sendStatus(200);
  });

What to Check When Signatures Don't Match

If you select "Verify" in the tab above, an input field for the expected value will appear. Paste the signature sent by the other party, and the tool will compare it with the newly calculated value and show whether it matches or not. It automatically strips GitHub-style `sha256=` prefixes and recognizes both hex and Base64 formats. If they don't match, check the following in order.

• Secret Key Format — The same key string will produce completely different bytes depending on whether it's interpreted as Text, Hex, or Base64. If the documentation says "a hex-encoded key," you must select the Hex option. This is the most common source of error.
• Output Format — If the other party expects Base64 and you send hex, it will obviously fail. If the lengths are almost double or half what you expect, this is likely the issue.
• Algorithm — Is it SHA-256 or SHA-1? You can tell immediately by the number of resulting bytes (32 vs 20).
• Whitespace or line breaks in the message — A single newline character copied by mistake will change the result. CRLF and LF are different bytes.
• Encoding — If the message contains non-ASCII characters, both sides must use the same encoding. This tool encodes the message as UTF-8.
• What is being signed — Is it just the body, or a timestamp and body concatenated in a specific format? This varies by service, so check the integration documentation.

Why You Shouldn't Use `==` for Comparison (Timing Attacks)

String comparisons typically check byte by byte from the beginning and stop immediately if they find a difference. This means that comparing a string that's wrong from the first byte takes less time than comparing one that's correct for the first ten bytes. By changing the signature slightly and measuring the response time thousands of times, an attacker can find the points where the comparison takes fractionally longer, indicating another correct byte has been found, and eventually reconstruct the entire correct signature.

Measuring this difference over the actual internet is difficult due to network noise. However, it becomes statistically viable within the same data center or if the attacker can send a massive number of requests. Most importantly, the defense costs nothing — all you have to do is use a different function.

HMAC vs. Simple Hashing: What's the Difference?

You might think, "Can't I just prepend the secret key and hash it?" But the `sha256(secret + message)` approach is actually vulnerable. Many hash functions, including SHA-256, are susceptible to length extension attacks due to their internal structure. An attacker who knows the hash of `secret+message` and the `message` itself can calculate a correct hash for a longer message with arbitrary data appended, without ever knowing the secret. In effect, they can forge a valid signature for a modified message.

HMAC is immune to this attack because it uses a construction that wraps the data in an inner and outer hash using the key. This is why the standard advice is to never roll your own signing scheme and always use HMAC.

What a Valid Signature Can't Prevent: Replay Attacks

HMAC only verifies one thing: that the message came from a party who has the key, and that it was not altered in transit. It says nothing about *when* the message was created or if you've already processed it. An attacker can copy a valid request and send it 100 times, and the signature will pass verification every single time.

• Include a timestamp in the data to be signed, and reject requests that are more than, say, five minutes old. The timestamp must be part of the signed payload, otherwise an attacker can just change it.
• Record event IDs to ignore messages you've already processed (idempotency). Webhooks can sometimes be delivered more than once even under normal conditions.
• Even with a valid signature, always cross-reference critical values like amounts and order numbers with your own database records.
• The secret key and message are processed only within this browser and are not sent to the server. The secret key is not even stored and will disappear on refresh. Still, pasting production keys into web tools is not recommended — use test keys to confirm the format, then move the logic into your code.