Reliable payment webhooks
A webhook arrives late, twice, out of order or forged, and a payment system has to be right every time. How to receive one so that none of that moves money.
By Nasfam Business engineering,
On this page
Expect every event more than once
A webhook is a provider calling your server when something happens: a payment settled, a payout failed, a deposit arrived. It feels like a function call. It is not one. The network between you can drop the request, your server can crash halfway through handling it, and the provider cannot tell a slow answer from a lost one.
So providers retry. The Standard Webhooks specification recommends retrying on a schedule spanning several days, with exponential backoff, until an attempt succeeds or delivery is judged impossible. The result is that your handler will see the same event more than once, events will arrive late and out of order, and some requests to your endpoint will not come from your provider at all.
A reliable handler is built for all four cases from the start. None of them is rare at volume.
Verify the signature before anything else
Your webhook URL is public. Anyone who finds it can send a request that looks like a payment notification. The signature is what tells a real delivery from a forged one, so check it before you read a single field.
Under Standard Webhooks, each delivery carries three headers: webhook-id, the event's unique id; webhook-timestamp, the Unix time in seconds; and webhook-signature, a space-separated list of signatures. The provider joins the id, the timestamp and the body with full stops and signs that string with your endpoint's secret.
- Use the raw body. Compute the signature over the bytes exactly as they arrived. A body parsed into an object and written out again is not the same bytes, and the check fails, or worse, passes for the wrong content.
- Recompute and compare in constant time. The specification asks for a constant-time comparison for symmetric signatures, so an attacker cannot learn a correct signature byte by byte from how long the comparison takes.
- Accept any one listed signature. A provider rotating its secret signs with both the old and the new one for a while, so the header can hold several values. Accept the delivery when one of them matches.
- Fail closed. A missing header, a malformed one or a mismatch is a refusal. Never fall back to trusting the body because the check could not run.
Keep the secret where your other secrets live, never in source code, and never in a log line. A logged signing secret lets anyone who reads your logs forge payments to you.
Refuse a replayed delivery
A valid signature proves the provider sent this body once. It does not prove the provider sent it now. Someone who captured a genuine delivery can send it again, signature and all.
Two checks close that door together. First, the timestamp: the specification tells consumers to refuse a timestamp outside an allowed tolerance of the current time, without naming a number. A few minutes covers ordinary clock drift; pick a value, write it down, and keep your servers' clocks synchronised. Second, the id: record every webhook-id you have processed and ignore a repeat.
Each check covers the other's gap. The timestamp alone still allows a replay inside the window; the id alone would oblige you to remember every id forever. With both, you only need to keep ids for as long as the window, plus whatever your provider's retry schedule spans.
Record the event before you act on it
Retries make duplicates certain, so the handler itself must be safe to run twice. The specification notes that the event id "is often used as an idempotency key", and that is the pattern: an inbox.
- Insert the event id into an inbox table with a unique constraint, in the same database transaction as the change the event causes. If the insert conflicts, you have seen this event: answer success and stop.
- Never record the id after the work. A crash between the work and the record means the retry does the work again. Never record it before, in a separate transaction, either: a crash after the record means the work is never done.
- Make the work itself idempotent where you can. A credit keyed by the provider's own reference cannot be applied twice even if two different events describe it.
Answer quickly, work afterwards
Providers wait a limited time for your answer, and a slow answer is treated as a failure and retried. If your handler calls three other services before it answers, every slow dependency becomes a duplicate delivery.
Verify, record the event durably, answer with a 2xx, and do the rest from a queue. The answer means "I have this event safely", not "I have finished with it". Answer with an error only when you could not record it: then the provider's retry is exactly what you want.
Do not trust the order, or the payload alone
Events arrive out of order. A "payment failed" can overtake the "payment processing" it follows, and a retry of an old event can arrive after newer ones. Apply an event only if it moves the object forward: keep the version or sequence number the provider sends, or the last state you applied, and ignore anything older.
Before you release value because of an event, such as crediting a balance or shipping an order, fetch the object from the provider's API and act on what it says now. The specification describes "thin" payloads, which carry only a reference for you to fetch, and "full" ones, which carry the object. Even with a full payload, the API is the authority and the event is the prompt to ask it.
Retries and dead letters on your side
Your queue worker can fail too: a bug, a database that is down, a dependency that times out. Retry the work with backoff, just as the provider retries the delivery. After a bounded number of attempts, move the event to a dead-letter queue and alert a person, instead of retrying it forever or dropping it.
A dead letter is not a failure to forget. It is an event your system owes work on. Once the cause is fixed, replay it through the same handler. Because the handler is idempotent, replaying the whole dead-letter queue is safe even if some of those events were partly processed.
Your endpoint can also be down long enough to miss deliveries entirely. The specification says a provider should disable an endpoint that answers 410 Gone, and recommends disabling one after prolonged failures. Find out how your provider behaves, watch for disabled endpoints, and after an outage reconcile against its list of events instead of assuming the retries covered everything.
Events about blockchain deposits
A provider that reports on-chain deposits may send an event when a deposit is first seen and another when it is final, and a deposit seen in a block that is later reorged away may never become final. Credit on the final event only, and treat the first as information for a pending state. The finality guide explains why.
A checklist
- The signature is verified over the raw body, in constant time, and a failure is a refusal.
- A timestamp outside the tolerance is refused, and processed ids are kept for at least the window.
- The event id is recorded in the same transaction as the change it causes.
- The handler answers after recording, and does the work from a queue.
- Stale events are ignored by version or state, and value is released only after the API confirms it.
- Failed work is retried with backoff, then dead-lettered with an alert, and replayed after the fix.
- The signing secret is never in source code or logs, and rotation is handled by accepting any listed signature.
Webhooks in Nasfam Business
Nasfam Business signs every webhook delivery under Standard Webhooks v1, so everything above applies to it unchanged. How to verify a delivery, which events it sends and how retries and replays work are in the webhooks guide of the documentation, with the verification itself in Verifying a delivery.
Sources
Each was read on 12 November 2026. Where a quotation appears in the guide, it is that page's own words.
- Standard Webhooks specification. The headers, the signed content, timestamp tolerance, the id as an idempotency key, constant-time comparison, retries, 410 Gone, and thin and full payloads.
- RFC 9110, section 9.2.2: idempotent methods. Why a request that changes state is not safe to repeat without a means to recognise the repeat.
Keep reading
Never pay twice: idempotent payouts
Idempotency keys, why a timeout is not a failure, and reconciling every outcome you could not see.
When is a crypto deposit safe to credit?
Confirmations, reorgs, and what each chain's own documentation says to wait for before a deposit is final.
