What is an HMAC webhook signature?
A webhook is an HTTP request a service sends to your URL when something happens: a payment succeeds, a form is submitted, a commit is pushed. Anyone who finds that URL can post to it too, so senders sign each request. They compute an HMAC (hash-based message authentication code) over the request body using a secret that only you and they know, and put the result in a header.
Your server repeats the calculation on the bytes it received. If its result equals the header, the request came from someone holding the secret and the body was not changed on the way. HMAC-SHA256 is the usual choice: 32 bytes of output, written as 64 hex characters or 44 base64 characters. The tool above does the same calculation your server should, so you can check a captured request by hand before debugging your code.
How popular senders sign webhooks
| Sender | Header | Value | Signed content |
|---|---|---|---|
| OSForms | X-osforms-Signature | <hex> | The exact raw JSON request body |
| GitHub | X-Hub-Signature-256 | sha256=<hex> | The raw request body (payload) |
| Stripe | Stripe-Signature | t=<unix>,v1=<hex> | <timestamp>.<raw body> (the t= value, a dot, then the body) |
| Shopify | X-Shopify-Hmac-SHA256 | <base64> | The raw request body |
Each row links to the sender's own documentation. Checked November 2026.
4 common webhook signature mistakes
1. Signing parsed JSON instead of the raw body
Body parsers turn bytes into objects, and turning the object back into a string with JSON.stringify or json.dumps rarely gives the same bytes: whitespace, key order, unicode escapes and number formatting can all change. Hash the raw body first, then parse it. In Express that means express.raw() on the webhook route, in a Next.js Route Handler await req.text(), and in Flask request.get_data().
2. Comparing with == instead of a constant-time function
A normal string comparison stops at the first different character, so its timing leaks how much of a forged signature was right. Use crypto.timingSafeEqual in Node.js (check the lengths first, because it throws when they differ) or hmac.compare_digest in Python.
3. Mixing up hex and base64
The same 32 bytes can be written two ways. OSForms and GitHub send hex, Shopify sends base64, and comparing one against the other always fails. Prefixes matter too: GitHub puts sha256= in front of the digest. Paste a header into the tool and it tells you which encoding it read.
4. Ignoring replay protection
A valid signature proves who sent the body, not that you are seeing it for the first time. Anyone who captures a signed request can send it again. Stripe signs a timestamp along with the body, and its libraries reject requests older than five minutes by default. OSForms and GitHub sign the body only, so store the IDs you have processed and skip repeats. For OSForms that is the submissionId inside the signed body, and since OSForms does not retry webhooks, a repeated ID is never a legitimate redelivery.
Verify a webhook signature in Node.js
One function covers hex and base64 senders, with an optional prefix. It uses only the built-in node:crypto module:
// verify-webhook.mjs (Node.js 18+)
import crypto from 'node:crypto';
export function verifySignature(rawBody, header, secret, options = {}) {
const { prefix = '', encoding = 'hex' } = options;
if (typeof header !== 'string' || !header.startsWith(prefix)) {
return false;
}
const received = Buffer.from(header.slice(prefix.length), 'utf8');
const expected = Buffer.from(
crypto.createHmac('sha256', secret).update(rawBody).digest(encoding),
'utf8'
);
// timingSafeEqual throws when lengths differ, so check that first
return (
received.length === expected.length &&
crypto.timingSafeEqual(received, expected)
);
}
// OSForms: verifySignature(raw, req.get('x-osforms-signature'), secret)
// GitHub: verifySignature(raw, req.get('x-hub-signature-256'), secret, { prefix: 'sha256=' })
// Shopify: verifySignature(raw, req.get('x-shopify-hmac-sha256'), secret, { encoding: 'base64' })And an Express route that reads the raw body before checking it:
// server.mjs
import express from 'express';
import { verifySignature } from './verify-webhook.mjs';
const app = express();
// Raw body on the webhook route. Register it before any app.use(express.json()).
app.post(
'/webhooks/osforms',
express.raw({ type: 'application/json' }),
(req, res) => {
const ok =
Buffer.isBuffer(req.body) &&
verifySignature(
req.body,
req.get('x-osforms-signature'),
process.env.OSFORMS_WEBHOOK_SECRET
);
if (!ok) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
console.log('Submission', event.submissionId, event.data);
res.sendStatus(200);
}
);
app.listen(3000);Verify a webhook signature in Python
The standard library has everything you need. With Flask, request.get_data() returns the exact bytes:
# verify_webhook.py (Python 3.8+, Flask 2+)
import hashlib
import hmac
import json
import os
from flask import Flask, abort, request
def verify_signature(raw_body: bytes, header: str, secret: str, prefix: str = "") -> bool:
if not header or not header.startswith(prefix):
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
# compare_digest is constant-time; comparing bytes means odd header text can't raise
return hmac.compare_digest(header[len(prefix):].encode(), expected.encode())
app = Flask(__name__)
@app.post("/webhooks/osforms")
def osforms_webhook():
raw = request.get_data() # exact bytes, read before any JSON parsing
signature = request.headers.get("X-osforms-Signature", "")
if not verify_signature(raw, signature, os.environ["OSFORMS_WEBHOOK_SECRET"]):
abort(401)
event = json.loads(raw)
print("Submission", event["submissionId"], event["data"])
return {"ok": True}For a base64 sender such as Shopify, build the expected value with base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode() and compare it the same way.
The OSForms webhook docs list every payload field and the request timeout. If you are still choosing where form data should go, start with how to handle form submissions without a backend.