Skip to main content
Six habits. The first two are the ones that matter most; the rest follow from them.

Acknowledge first, work afterwards

Answer 2xx as soon as you have the payload, then queue the work. Your endpoint has 30 seconds, and a handler that does its processing inline is a handler whose latency is your database’s latency. The shape that works: verify the signature, write the event to your own queue or table, answer 2xx, process from there.

Make processing idempotent

Design so that handling the same event twice changes nothing the second time. Key on event_id, which a retry and a replay re-send unchanged, and record what you have already handled. A refund sent under a deprecated name carries its own event_id, so key refunds on deposit_id. See Deprecated deposit events. Do this even where you believe an event arrives once. The failure it prevents is paying someone twice.

Treat the event as a signal, not as the truth

The payload tells you something changed. When the decision matters — releasing goods, paying someone, telling a customer their money arrived — read the resource back and act on what it says now. An event describes a moment. The resource describes the present, and by the time you process a queued event those can differ.

Never trust an unverified payload

Check the signature before you read a single field. An endpoint that acts on the body first and verifies later has already acted. See Validate signatures.

Ignore what you do not recognise

Answer 2xx to an event name you do not handle, and log it. New events are added over time, and a handler that throws on an unfamiliar name turns an addition into an outage. Answering a 4xx other than 408 or 429 discards the event for good. When a delivery fails lists what is retried. The same goes for unfamiliar fields inside a payload you do handle.

Keep the endpoint available

A brief outage costs you nothing, because a transient failure is retried. A longer one does. The retries buy you minutes, not a day, so uptime is still part of the integration. Where correctness depends on not missing something, pair the webhook with a read: reconcile against the resource on a schedule, so a gap is something you notice rather than something a customer reports.