Webhooks: Design and Reliability

Standard Webhooks recommends a JSON body with three top-level fields: a type such as invoice.paid, a timestamp for when the event occurred, and a data object with the event details. Event types should be grouped hierarchically with dots, which lets consumers subscribe to and route families of events.

{
  "type": "invoice.paid",
  "timestamp": "2026-02-11T09:30:12.512Z",
  "data": {
    "id": "inv_8Kd2",
    "customer_id": "cus_19aF",
    "amount": 4900,
    "currency": "usd"
  }
}

The bigger choice is how much data to send. The specification compares thin and full payloads. A full payload includes everything about the changed object, so the consumer rarely needs another API call. A thin payload includes only identifiers, which keeps messages small and forces the consumer to fetch current state. The specification also recommends keeping payloads small, and sending a link rather than embedding large assets.

Thin payloads have a reliability benefit that is easy to miss. Because the consumer fetches the current state when it processes the event, a delayed or out-of-order event cannot overwrite newer data with older data. Hookdeck notes that Stripe offers thin events for some event types for this reason.

Two other habits help consumers.

• Publish a schema for every event type and an example payload, as the specification recommends.
• Treat new event types and new fields as additive. GitHub warns that it continues to add new event types and new actions, so consumers should check the event type and action before processing and ignore what they do not handle.

A webhook endpoint is a public URL. Anyone who finds it can send it requests, so the consumer must verify that each delivery came from the real provider and was not altered. The webhooks.fyi reference describes HMAC as by far the most popular authentication and message security method used on webhook requests: the provider and the consumer share a secret, the provider signs each message with it, and the consumer recomputes the signature to check it.

Standard Webhooks specifies what to sign: the message ID, the timestamp and the body, joined with full stops, as msg_id.timestamp.payload. It sends them in three headers.

webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1674087231
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Signing the ID and timestamp along with the body matters. The specification's verification guidance says consumers should check that the webhook-timestamp header has a timestamp that is within some allowable tolerance of the current time, which blocks an attacker from replaying an old, validly signed request.

On the receiving side, three mistakes are common.

1. Verifying a re-serialized body. The specification warns that signatures break on the smallest change, and that consumers often parse the JSON and serialize it again before verifying. Always verify against the raw request bytes.
2. Comparing signatures with ==. GitHub's validation guide says never use a plain == operator and recommends a constant-time comparison such as crypto.timingSafeEqual to resist timing attacks.
3. Putting secrets in the URL. GitHub's best practices warn against including API keys or credentials in the payload URL and recommend a high-entropy webhook secret instead.

Providers have their own duties. Standard Webhooks recommends a unique signing key per endpoint, and its signature header is a space-separated list so that a provider can sign with both the old and new key during rotation. Consumers try each signature until one matches, and the secret changes without downtime.

A provider is responsible for delivery. The Standard Webhooks specification puts it directly: it is up to the webhook producer to retry sending the webhook until an attempt succeeds or delivery is judged impossible.

Its recommendations for providers:

• Treat only 2xx as success. Any other status, a timeout or a reset connection is a failure.
• Retry with exponential backoff and jitter over a schedule that spans multiple days. The jitter prevents retries from all arriving at once and adding to the load that caused the failure.
• Honor the receiver's signals. A 410 Gone means the endpoint no longer wants events and should be disabled. A retry-after header should shape the next attempt.
• Use a reasonable request timeout. The specification suggests a value between 15 and 30 seconds as of the version read on 2026-10-17.
• Disable endpoints that fail for a long time and tell the customer through another channel, such as email.
• Protect against server-side request forgery. Customers choose the URLs, so an attacker can point a webhook at internal services. The specification recommends sending through a proxy that blocks internal addresses and isolating the delivery workers.

Give customers a delivery log with each attempt's status and response, and a button to resend. Without it, every failed delivery becomes a support ticket.

The receiver's first job is to acknowledge quickly. GitHub's documentation, as read on 2026-10-17, says your server should respond with a 2XX response within 10 seconds, or GitHub terminates the connection and counts the delivery as a failure. It suggests a queue so the server can respond at once and process the payload in the background.

Hookdeck makes the same argument for scale. Webhooks often arrive in bursts, such as billing runs or mass retries after an outage, and processing them synchronously leads to timeouts, more retries and a retry storm. The fix is to queue everything first.

A receiving endpoint should do only this:

1. Read the raw body.
2. Verify the signature and timestamp. Reject failures with a 4xx.
3. Write the event to a durable queue or table, keyed by its ID.
4. Return 2xx.

Everything else, including database updates, emails and calls to other APIs, happens in a worker that reads from the queue. Watch the queue's depth and the age of its oldest message, the two back-pressure measures Hookdeck recommends, so you know when workers fall behind.

Because delivery is at least once, every handler must be safe to run twice. Hookdeck's idempotency guide explains that automatic retries are the primary source of duplicate webhook deliveries, and that timeouts are the most dangerous case: you processed the event, but responded too slowly, so a retry is already on its way.

Standard Webhooks gives every event a unique ID that stays the same across retries, intended for use as an idempotency key. Two implementations work well.

Use a natural unique key. If the event creates an order, put a unique constraint on the provider's order ID. A duplicate insert fails, and the handler treats that failure as success.

Record processed events. Keep a table of event IDs with a unique constraint.

CREATE TABLE processed_webhooks (
  event_id     text PRIMARY KEY,
  received_at  timestamptz NOT NULL DEFAULT now(),
  status       text NOT NULL DEFAULT 'processing'
);

Insert the ID before doing the work. If the insert fails, the event is already handled or in progress, so skip it. Hookdeck's guide stresses the order: mark events as processed before executing side effects, because sending an email first and recording it second means a crash in between sends the email again on retry. Where possible, do the insert and the database changes in one transaction.

Ordering needs a separate rule. Events can arrive in any order, so never apply one blindly over current state. Either fetch the current state from the provider's API when processing, the thin payload approach, or compare the event's timestamp or version with what you have stored and ignore older updates.

Even with all of the above, events go missing: an endpoint is down longer than the retry window, a bug drops events for a day, or a provider has an incident. Hookdeck describes three layers of recovery: retries handle minutes of failure, replay handles hours, and reconciliation handles everything else.

• Retries come from the provider automatically.
• Replay means resending stored events after you fix a problem. GitHub recommends redelivering missed webhooks once your server is back up, and notes that a redelivery carries the same delivery ID, so idempotency keeps replays safe.
• Reconciliation is a periodic job that reads current state from the provider's API and corrects your copy. For payments, subscriptions and anything else that affects money or access, build it before you need it.

A checklist covering both sides:

Agents and automations increasingly react to webhooks, which raises the cost of a duplicate or a missed event. Quanta Intelligence agents that act on incoming events follow the same rule: verify, record the event ID, then act.