A webhook is an HTTP POST your service sends to a URL the customer controls whenever an event happens, like a payment succeeding. It lets the customer's app react in real time instead of polling your API for changes.

How does HMAC signature verification work?

Your service computes an HMAC-SHA256 of the raw request body using a shared secret and sends it in a header. The receiver recomputes the same hash and compares it with a constant-time check. If they match, the payload is authentic and untampered.

Why must webhook handlers be idempotent?

Because deliveries can be retried, the same event may arrive more than once. Handlers must dedupe using the event id so processing it twice has no extra effect — for example, not charging a customer or sending an email twice.

What should happen when a webhook delivery fails?

A non-2xx response or timeout should trigger retries with backoff, up to a maximum number of attempts. After the final failure the event is marked failed and should be replayable from a dashboard so no event is silently lost.

How quickly should a receiver respond?

Respond with 200 OK as fast as possible, ideally within a few seconds, then process the payload asynchronously. Doing slow work before responding risks a timeout, which your service interprets as a failure and retries unnecessarily.

What is the Webhook Documentation Builder?

Generate complete webhook documentation with event types, JSON payload schemas, HMAC signature verification code, retry and backoff policy, and idempotency guidance — ready to drop into your developer docs. It runs free in your browser on Gera Tools, with nothing uploaded.

Webhook Documentation Builder

Name: Webhook Documentation Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

What good webhook documentation includes

Many webhook implementations ship with poor documentation, and the gap shows up immediately when developers integrate: they misread the signature header format, process events synchronously and cause timeouts, or fail to handle retries and end up with duplicate charges or emails. Well-structured documentation eliminates these failure modes before they happen.

Signature verification section

This is the most critical part. Document:

The exact header name carrying the signature (for example, X-Webhook-Signature or X-Hub-Signature-256).
The signing algorithm (HMAC-SHA256 is standard).
Whether the signature value is raw Base64, hex-encoded, or prefixed with sha256=.
That the receiver must sign the raw request body bytes — not the parsed, re-serialised JSON.
The importance of constant-time comparison (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python) to prevent timing attacks.

A code snippet for each common language (Node.js, Python, Ruby, PHP) removes friction for the majority of integrators.

Event payload section

For each event, show a complete realistic JSON example — not just a field list. A developer integrating a payment.completed event needs to see whether amount is in cents or decimal dollars, whether created_at is a Unix timestamp or ISO 8601, and what status values are possible. Abstract schemas do not answer these questions; concrete examples do.

Retry and delivery policy section

Document clearly:

How many delivery attempts your system makes and over what time window.
The backoff strategy (exponential is standard — for example, 1 min, 5 min, 30 min, 2 hr, 24 hr).
What HTTP status codes you treat as success (usually 2xx) versus failure.
Whether failed events can be replayed from a dashboard.
The timeout on the receiver response — typically 5 to 30 seconds.

Idempotency guidance

Every handler must be idempotent because any event may be delivered more than once. The standard pattern: extract the event id, check whether you have already processed it (in a database or cache), and skip processing if you have. Document this explicitly — it is the single most common integration mistake.

Tips

Always sign the raw body, not the parsed JSON. Re-serializing changes bytes and breaks signature verification.
Tell receivers to respond 200 OK immediately and process asynchronously. A slow handler causes timeouts, which trigger pointless retries.
Make every example payload concrete. A field list like id, amount, currency, status becomes 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.