Webhooks 101: building a reliable webhook handler for payments

A webhook is an HTTP request that the payment provider sends to a URL you choose when an event happens. Instead of your system repeatedly asking "has this payment completed yet?", the provider tells you as soon as it knows.

A typical event contains an event type (for example payment.captured), an event ID, a timestamp and details of the object it relates to — the payment, refund or payout.

Your webhook URL is reachable from the internet, so anyone could send it a request that looks like a payment success. Providers sign webhooks — typically with an HMAC of the raw request body using a secret shared with you — so you can prove the request is genuine.

raw_body  = read the request body exactly as received
expected  = HMAC_SHA256(webhook_secret, raw_body)
received  = request header carrying the signature
if not constant_time_equals(expected, received):
    respond 400 and stop

• compute the signature over the raw body, before any JSON parsing or re-formatting;
• use a constant-time comparison;
• keep the webhook secret in server configuration, never in code or client-side apps;
• reject events with timestamps far outside your tolerance, to limit replay.

Check your provider's documentation for the exact header name and signing method — see Paynancial webhooks.

Providers expect a fast success response. If your endpoint is slow or times out, the provider will treat the delivery as failed and retry it — creating duplicates and a growing backlog.

1. verify the signature;
2. store the event (or put it on a queue);
3. respond with a 2xx status straight away;
4. process the event in a background worker.

Retries mean the same event can arrive more than once. Your processing must be idempotent: handling an event twice has the same effect as handling it once.

• record each event ID when you process it, and skip IDs you have already seen;
• make state changes conditional — "mark order paid if not already paid" rather than "add a payment";
• never trigger side effects such as emails or shipments twice for the same event.

Events can arrive out of sequence — a refund event could be processed before the capture event it relates to, if deliveries are retried. Protect against this by:

• treating the object's current status as the truth, fetching it from the API if in doubt;
• allowing only valid status transitions, and ignoring updates that would move an object backwards;
• using timestamps or version numbers on objects, where available.

Webhooks can be delayed or, if your endpoint was down long enough, missed. A scheduled job that checks the status of recent payments that are still pending in your system catches anything that slipped through. It is also the right fallback when a customer returns from checkout before the webhook arrives.

• HTTPS endpoint, separate secrets for sandbox and live;
• signature verified on the raw body with a constant-time comparison;
• event stored and acknowledged with a 2xx quickly;
• processing in the background, idempotent by event ID;
• status transitions validated; out-of-order events handled;
• alerting when deliveries fail or the backlog grows;
• a scheduled status check for payments still pending.