How webhook signatures work (HMAC) and how to inspect them

The quick answer: most providers sign each webhook by computing an HMAC (usually HMAC-SHA256) over the raw request body, often together with a timestamp, using a secret only you and the provider know. They send the result in a header. Your server repeats the calculation and rejects the request if the values don't match.

What does a signed webhook look like?

The exact header name and format vary by provider. Common patterns:

PatternExample header
hex digest with an algorithm prefixX-Signature-256: sha256=5d41402a…
timestamp plus signatureSignature: t=1731326400,v1=9f86d081…
base64 digestX-Signature: Kq5sNclPz7QV2+lfQIuc6R7oRu0=

Always follow your provider's documentation for the exact format.

How do I compute an HMAC signature locally?

With openssl and a made-up test secret:

body='{"event":"test","id":1}'
secret='test_secret_only'
sig=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$secret" | sed 's/^.* //')
echo "$sig"

How do I see the signature headers a request carries?

Send a signed request to an echo endpoint and read headers in the response:

curl https://webhook.plus/anything/plus/signed \
  -H 'content-type: application/json' \
  -H "X-Signature-256: sha256=$sig" \
  -d "$body"

Compare the echoed data (the raw body) with what you signed. If they differ by even one byte (whitespace, key order, a trailing newline), the signature won't verify.

Why do signatures fail to verify?

  • Parsing before verifying. Frameworks often parse JSON and re-serialise it. Verify against the raw bytes, not the parsed object.
  • Wrong secret. Test and live modes usually have different signing secrets.
  • Encoding mismatch. Hex versus base64, or a missing sha256= prefix.
  • Clock skew. Timestamped schemes reject requests outside a tolerance window.
  • Unsafe comparison. Use a constant-time compare, such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js.

A minimal verifier in Python

import hmac, hashlib
def valid(raw_body: bytes, header: str, secret: bytes) -> bool:
    expected = 'sha256=' + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Keep real secrets out of test tools

Use a throwaway secret like the one above when experimenting. Requests sent to webhook.plus, headers included, are recorded and kept indefinitely, so never send a production signing secret or real signed payloads.

Frequently asked questions

Should I verify the signature against parsed JSON?

No. Verify against the raw request body bytes. Re-serialised JSON often differs in whitespace or key order, which changes the HMAC.