Webhooks are only useful if they are documented
Webhooks let your customers react to events the instant they happen — but only if they can verify the requests, understand the payloads, and handle retries correctly. This builder produces complete, copy-ready webhook documentation: how to receive and verify requests, what each event’s payload looks like, and how your retry policy behaves.
How it works
You set the authentication method — typically HMAC-SHA256. The tool generates the verification recipe: your service signs the raw request body with a shared secret and sends the signature in a header; the receiver recomputes the HMAC and compares it with a constant-time check (timingSafeEqual) to prevent both tampering and timing attacks.
For each event you provide a type, a description, and its fields. The tool renders a realistic JSON payload for each one, choosing sensible example values based on field names (ids, amounts, timestamps). It also documents the retry policy — max attempts and backoff strategy — and stresses idempotency: because retries can deliver the same event twice, handlers must dedupe on the event id.
Tips and example
- Always sign the raw body, not the parsed JSON. Re-serializing changes bytes and breaks signature verification.
- Tell receivers to respond
200 OKimmediately and process asynchronously. A slow handler causes timeouts, which trigger pointless retries. - Make every example payload concrete. A field list like
id, amount, currency, statusbecomes a JSON block developers can copy and test against. - Document that failed events are replayable. Developers trust a webhook system far more when they know a missed event is not lost forever.