Webhook Documentation Generator
Define your webhook events and sample payloads, then generate complete, publishable documentation — an event catalog, an inferred payload field reference, an HMAC-SHA256 signature-verification snippet and a delivery & retry guide. Parsed entirely in your browser.
{
"id": "evt_3PqL9aK2xZ",
"type": "payment.succeeded",
"created": 1750000000,
"data": {
"object": {
"id": "pay_1Mx8aZ",
"amount": 4999,
"currency": "usd",
"status": "succeeded",
"captured": true,
"customer": {
"id": "cus_8Hb2",
"email": "ada@example.com"
},
"metadata": {
"order_id": "ord_5521"
}
}
}
}Verify signatures & handle delivery
HMAC-SHA256 over the raw request body, comparing the X-Signature header in constant time against a secret from WEBHOOK_SECRET.
// Express middleware — verify the X-Signature header (HMAC-SHA256)
import crypto from "crypto";
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// IMPORTANT: verify against the *raw* request body, not the parsed object.
// In Express, capture it: app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
function verifyWebhook(req, res, next) {
const signature = req.get("X-Signature");
if (!signature) return res.status(400).send("Missing X-Signature");
const expected = crypto
.createHmac("sha256", WEBHOOK_SECRET)
.update(req.rawBody)
.digest("hex");
const a = Buffer.from(signature, "utf8");
const b = Buffer.from(expected, "utf8");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send("Invalid signature");
}
next();
}From sample payloads to trustworthy webhook docs
Good webhook documentation answers three questions before an integrator writes a line of code: what events fire, what each payload looks like, and how to trust that a request really came from you. This tool builds all three from the one artifact you already have — a few representative sample payloads. The event catalog and the inferred field reference are derived directly from those samples, so the field paths your consumers read here are precisely the ones they'll receive, down to nested objects and array element shapes.
The signature section is where most integrations quietly break. The generated HMAC-SHA256 snippets hash the raw request body, not a re-serialized object, because re-serialization can reorder keys or change whitespace and produce a signature that never matches. They also compare signatures in constant time — timingSafeEqual, hmac.compare_digest, hash_equals — so an attacker can't use response timing to forge a valid signature byte by byte. The header name and secret variable are yours to set and flow through every language template.
The delivery and retry reference encodes the contract that makes webhooks reliable: acknowledge with a fast 2xx, expect retries with backoff on any failure or timeout, and de-duplicate on the stable event id because the same event can arrive more than once. Building handlers that are idempotent and that offload heavy work asynchronously is the difference between an endpoint that shrugs off a retry storm and one that double-charges a customer.
Designing the payloads themselves pairs well with the JSON Schema Explorer; for the auth headers your endpoint sits behind, see the API Authentication Builder; and to document the rest of your surface, the OpenAPI Documentation Generator covers your REST endpoints.
Trusted by Backend & Platform Engineers
“We ship a public webhooks product and this got our docs from sample payloads to a full event catalog, field reference and verification snippets in minutes. The field-path inference matched our real payloads exactly, and the Node example correctly verifies against the raw body — which is the thing everyone gets wrong first.”
“The retry and idempotency reference is exactly the guidance our integrators kept asking for, written clearly. I pasted three of our event payloads, set the header to X-Webhook-Signature, and handed the output straight to the docs team. No data left the browser, so I was comfortable using production samples.”
“Great for live demos — define an event, generate the HMAC snippet in Python and PHP side by side, copy and run. I'd love a Go template too, but the three it has cover most of our audience and the constant-time comparison being baked in is a detail I appreciate.”
“I consume a lot of webhooks and use this in reverse: paste a provider's sample payload and instantly get the field reference and a verification handler I can trust. The note about idempotency on the event id saved a teammate from double-processing payments during a retry storm.”
Love using our calculator?
Related API tools
Related Articles
Dive deeper with our expert guides and tutorials related to Webhook Documentation Generator
event catalog · field reference · HMAC verification · retries · in-browser · Last reviewed: 2026-06