Public API

Designing a reliable webhook consumer

A reliable webhook consumer does four things: verify, acknowledge fast, dedupe, and reconcile. Verify the signature over the raw body, return 200 within 10 seconds, deduplicate on the event id, and treat delivery as unordered. Get these right and webhooks become boringly dependable.

2 min read

Verify1
Ack fast2
Dedupe + reconcile3 & 4

The four properties

  1. Verify — HMAC over the raw body, fresh timestamp. See signature verification.
  2. Acknowledge fast200 within the 10-second timeout; process asynchronously.
  3. Deduplicate — on the event id, because delivery is at-least-once. See idempotent handlers.
  4. Reconcile — treat events as unordered; trust created and live state.

Put together

The verify-then-enqueue pattern satisfies all four cleanly: verify and enqueue synchronously (fast ack), then dedupe and reconcile in the worker. It is the shape to reach for at any real volume.

Frequently asked questions

Which property is most often skipped?

Idempotency. Teams verify and ack correctly, then process an event twice on a redelivery. Dedupe on the event id from day one.

Do I need all four for a simple integration?

Verify and ack are non-negotiable. Dedupe and reconcile matter the moment an event has a side effect you would not want applied twice or out of order — which is almost always.

Funding for UK limited companies

Credicorp lends to your company, not to you personally — short-term working capital with no personal guarantee. See what your business could access.