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:
| Pattern | Example header |
|---|---|
| hex digest with an algorithm prefix | X-Signature-256: sha256=5d41402a… |
| timestamp plus signature | Signature: t=1731326400,v1=9f86d081… |
| base64 digest | X-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_digestin Python orcrypto.timingSafeEqualin 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.