HMAC-SHA256 Signature Verification: Check Your Values

PublishedToolHMAC Generator

Contents
  1. What usually happens when a webhook signature doesn't match
  2. How to calculate an HMAC value yourself without a tool
  3. 4 things people often miss when a signature doesn't match
  4. Recap
  5. Frequently asked questions

When an HMAC signature that arrives in a webhook or API response doesn't match the value you calculated yourself, it's almost never a security breach. Usually one of the three inputs — the message, the secret key, or the hash algorithm — is slightly different. You get the same signature only when all three match exactly.

This post shows real calculated values as examples and walks through what to check first when a signature doesn't match. This isn't a problem that needs expert judgment. It's a procedure you finish by feeding in the same inputs and comparing the output with your own eyes.

Summary ① An HMAC signature is calculated from three inputs — the message, the secret key, and the hash algorithm — and all three must be exactly the same for the value to match. ② The usual causes are whitespace and line breaks, letter case, encoding (hex vs. Base64), and a different algorithm. ③ Verification means recalculating with the same message, key, and algorithm, then comparing the result character by character.

What usually happens when a webhook signature doesn't match

When an external service sends a webhook to announce an event like a completed payment or an order status change, it's common to send the request body (payload) along with an HMAC signature calculated from that body in a header. The receiver calculates its own signature with the same secret key and compares it to the value in the header.

When that comparison fails, it's easy to suspect a bug in your code or a forged request. In practice, though, the payload often isn't used as-is — it gets parsed and turned back into a string, and that round trip adds an extra space or a line break.

HMAC is deliberately designed to be sensitive to differences this small. Change one character in the message, the case of one letter in the secret key, or the hash algorithm, and the result is a completely different string from start to finish.

How to calculate an HMAC value yourself without a tool

HMAC is a standardized construction defined in RFC 2104 that signs a message using a secret key and a hash algorithm. You can reproduce this calculation right in your terminal, with no special program.

macOS and Linux ship with OpenSSL, so this command performs the same calculation:

echo -n "order:1001,amount:5000" | openssl dgst -sha256 -hmac "mySecretKey"

Running this command gives you:

SHA2-256(stdin)= 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4

This is the value you get when the message is order:1001,amount:5000, the secret key is mySecretKey, and the algorithm is SHA-256. Feed in the same three inputs and you get this value every time, regardless of operating system or programming language.

Checking that other languages produce the same value

We also confirmed that Python's hmac module produces the same value for the same message and key.

import hmac, hashlib
hmac.new(b"mySecretKey", b"order:1001,amount:5000", hashlib.sha256).hexdigest()

If you forget the -n option in echo, a line break gets added to the end of the message automatically, and you get a completely different value even with the same message, key, and algorithm. I'll show that with real numbers in the next section.

Let's check it with our free HMAC Generator.

HMAC Generator

It calculates instantly in your browser with the Web Crypto API, and the message and secret key you enter are never sent to a server.

4 things people often miss when a signature doesn't match

Using the same message order:1001,amount:5000 and the same secret key mySecretKey, here's what you get for a SHA-256 signature when you change just one tiny thing at a time.

Original:             order:1001,amount:5000
SHA-256 result:       148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4

Line break at end:    order:1001,amount:5000  (one newline character after it)
SHA-256 result:       015bc2c0bf5cc82fd005e37b7a2b0ae8777e41a109bae303b263aaa162f32cff

First letter uppercase: Order:1001,amount:5000
SHA-256 result:       11c1403b448d39601f4a14119514f6a44b16bdcb378f384d767ffafc0054ffb2

When the message itself is slightly different

The message looks nearly identical to the eye, but the result is completely different from the very first character. This is often what "the signature doesn't match" actually means. The secret key didn't leak and the logic isn't wrong — the two strings you're comparing are genuinely different.

When the encoding or the algorithm is different

Even the same signature looks different when it's written in a different format. The result from the original example above in Base64 is FIvsndY2Z+3Gs9N/nn9WB8dRRL0mcVnYQ+yJiwZnzqQ=, which is just the same signature written in Base64 instead of hex.

If the header gives you a hex value and your side calculates Base64, of course they look different when you compare them.

If the algorithm itself is different, even the length is different. For the same message and key, SHA-1 produces a 40-character hex string, SHA-256 produces 64, SHA-384 produces 96, and SHA-512 produces 128.

Calculating the message above with SHA-1 gives d67244f34d44c077a2a3dada4528c8284c2951cb — a different length and a different value from SHA-256. Here are the four causes:

CauseSymptomHow to check
Trailing whitespace or line break in the messageThe original looks the same but the value differsCheck directly for a space or newline at the end of the message
Letter case differenceOnly part of a field name or value differsCompare character by character to confirm you copied the original payload as-is
Encoding difference (hex vs. Base64)The length and character set differ (Base64 includes +, /, =)First confirm whether the signature you're comparing is hex or Base64
Algorithm mismatchThe value's length itself differs (40/64/96/128 characters)Check that the algorithm the sender specified matches the one you selected

Recap

  1. An HMAC signature is determined by three inputs — the message, the secret key, and the algorithm — and all three must match for the value to match.
  2. Add even one space or line break to the message and the result changes completely.
  3. If the lengths differ, it's almost always the encoding (hex vs. Base64) or the algorithm.
  4. Verifying is simple: recalculate with the same three inputs and compare character by character with the value you received.
  5. Recalculating with the openssl dgst command or a browser tool helps you narrow down which input is off.
HMAC Generator

It calculates instantly in your browser with the Web Crypto API, and the message and secret key you enter are never sent to a server.

Frequently asked questions

I'm using the same message and key, but the value is different every time. Is that normal?

No. HMAC is a deterministic calculation: given the same message, secret key, and algorithm, it always produces the same value, wherever and whenever you calculate it. If the value keeps changing, one of the three is actually changing. A common case is a message that includes something that varies, like the current time.

Should the value be in hex or Base64?

Both just represent the same result bytes, and neither is the "right" answer. Match whichever format the sender used to encode the signature. If the value contains only 0-9 and a-f, it's hex. If it mixes in +, /, and =, it's Base64.

How do I figure out which algorithm was used?

Leave the message and key as they are, calculate with SHA-256, SHA-384, SHA-512, and SHA-1 in turn, and start with the algorithm whose output length matches the value you received. Documentation and API specs usually state the algorithm, so checking there first is the most reliable route.

Do Korean characters or special characters in the message change the value?

If the encoding is the same (UTF-8, for example), the same string always converts to the same bytes and produces the same value. But if the character encoding changes during storage or transmission — one side UTF-8, the other EUC-KR, say — characters that look identical have different actual bytes, so the result can differ.

This article was adapted from our Korean original. Read the Korean original

Related articles

  1. HTML Email Preview: Check Mobile and Desktop RenderingSee how your HTML email code renders at 375px, 768px, and full width in the browser, and why table layouts and inline styles hold up better in inboxes.
  2. HTML Entity Conversion: 5 Character Encoding RulesSee how HTML entity conversion works: which entities replace five special characters, and how to decode numeric and named entities back to text.
  3. HTML Special Character Escape: Convert &, <, >, and QuotesWhy &, <, >, " and ' break HTML code samples, and how to escape and unescape them with a 1:1 table and the right replacement order.
  4. HTML to JS String Escaping: Quote vs Backtick Modes ExplainedLearn why quote mode splits HTML into per-line strings joined with \n and +, while backtick mode keeps line breaks, plus common syntax error fixes.
  5. How HTML Minification Works: Whitespace, Comments, and SavingsSee what HTML minification removes—whitespace between tags and comments—why script, style, pre, and textarea stay intact, and how savings % is computed.
  6. htpasswd Generator: Create a .htpasswd File Without InstallingBuild a one-line .htpasswd entry for Apache or Nginx Basic Auth in your browser. See the username:hash format and how {SHA} and {SHA256} are computed.

Related tools