Webhooks
How deliveries are verified, and why one may arrive twice.
As a payment's status changes, Atlas sends a signed POST to the
callback_url you supplied on the payment request.
In the body and in the status endpoint the payment is called a payin — the
same object, an older name. The body is JSON. Respond with any 2xx status to
acknowledge it.
A payout's callbacks work the same way, to the callback_url you supplied on
the payout request. Everything on this page — the
signature rule, the retries, the coalescing — applies to both. What differs is
which statuses are delivered and one extra field, sub_status, in the body;
both are covered under
Payouts. The body below is a
payin's.
{
"id": "321",
"external_id": "123",
"amount": "3.77",
"currency": "USD",
"status": "COMPLETED",
"updated_at": "2026-07-07T14:30:00Z",
"created_at": "2026-07-07T14:30:00Z",
"signature": "966f96fb41ec3745aa135c7e770909c911b9ebded7113f1a35e8edea86c1001d"
}| Field | Description |
|---|---|
id | The payin's id — the same value returned as payin_id from /atlas/payment. |
external_id | Your own reference, if you sent one. Omitted entirely when there isn't one — not an empty string. |
amount | Payin amount, as a decimal string. |
currency | ISO 4217 currency code. |
gate_amount | Amount on the gateway side, when a conversion happened. Omitted when there isn't one. |
gate_currency | Currency on the gateway side, when a conversion happened. Omitted when there isn't one. |
status | Current status — one of the values below. |
updated_at | ISO 8601 timestamp of this status change. |
created_at | ISO 8601 timestamp of the payin's creation. |
signature | HMAC-SHA256 over the body (see below) — a different rule from request signing. |
For a payin, the status a webhook delivers is one of PROCESSING,
ACCEPTED, COMPLETED, FAILED or CANCELED — CREATED and ROUTED are
internal steps nothing is delivered for. EXPIRED still arrives for payments
created before this status set changed, and never for a payin created since —
your integration should keep handling it, but should not expect to see it on
new payments. A payout's delivered set is a different one — see
Payouts.
Verifying the signature
The webhook signature is HMAC-SHA256 under your hex-decoded merchant secret, same as a request — but the canonical string is built differently:
- Take the values of every field in the body that's present, except
signature(omitted optional fields aren't included). - Sort the values themselves, ascending, byte-wise — not the field names.
- Join them with a single pipe
|. - HMAC-SHA256 the result with your hex-decoded merchant secret; the signature is the lower-case hex digest.
For the body above, the three omitted-when-empty fields aside, the values sort to:
123|2026-07-07T14:30:00Z|2026-07-07T14:30:00Z|3.77|321|COMPLETED|USDSecret (hex): a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. Signature:
966f96fb41ec3745aa135c7e770909c911b9ebded7113f1a35e8edea86c1001dSorting values rather than field names means you don't need to know the
field names in advance to verify a payload you don't recognize the shape of
— but it also means this is not the same code path as
request signing. Don't reuse one sign() for both.
Delivery and retries
- Delivery counts as successful on any
2xxHTTP response. - On anything else, delivery is retried up to 5 more times — 6 attempts
in total — with backoff
1m → 5m → 30m → 2h → 6hbetween successive attempts. If the sixth attempt also fails, delivery is given up on and reported internally as failed. - Independently of that, a delivery is also given up on — reported internally as expired — if 24 hours pass since the status was first queued, whichever comes first. In practice the retry ladder above resolves in under 9 hours, so this ceiling mostly matters if delivery itself is slow to fail (a callback endpoint that hangs rather than erroring, for example) rather than as the thing that ends a normal retry sequence.
- Statuses are coalesced, on a best-effort basis: each status has a
fixed rank (
COMPLETEDoutranks everything;CREATEDis lowest), and when a payin's status changes again before an earlier delivery has gone out, the earlier one is dropped in favour of the newer one — comparing against whatever was most recently queued for that payin, not against what's actually been delivered yet. That comparison is recorded opportunistically and never blocks a delivery if it fails, so treat coalescing as something that usually keeps you from seeing a stale status arrive after a fresher one, not as a guarantee — see When to poll versus wait.
Why a delivery may arrive twice
Two different things can look like "twice," and only one of them is a bug in your handler if you don't plan for it:
- A retried delivery of the same status. If your endpoint processed a
callback correctly but its
2xxresponse didn't make it back — a timeout, a network blip, a proxy that ate the response — Atlas has no way to know that, and retries on the same backoff ladder as any other failure. Your handler needs to be safe to run twice for the sameid+status. - Genuinely different statuses for the same payin.
PROCESSINGand thenCOMPLETEDfor the sameidisn't a duplicate — it's the payin actually progressing, and both were worth delivering. Coalescing only drops a stale status once a later one has been queued behind it; it doesn't collapse a real sequence into one call.
Treat each delivery as "the payin now has this status," not as an event that must never repeat, and both cases are handled the same way: apply the status if it's new information, and no-op if it isn't.