Atlas API

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"
}
FieldDescription
idThe payin's id — the same value returned as payin_id from /atlas/payment.
external_idYour own reference, if you sent one. Omitted entirely when there isn't one — not an empty string.
amountPayin amount, as a decimal string.
currencyISO 4217 currency code.
gate_amountAmount on the gateway side, when a conversion happened. Omitted when there isn't one.
gate_currencyCurrency on the gateway side, when a conversion happened. Omitted when there isn't one.
statusCurrent status — one of the values below.
updated_atISO 8601 timestamp of this status change.
created_atISO 8601 timestamp of the payin's creation.
signatureHMAC-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:

  1. Take the values of every field in the body that's present, except signature (omitted optional fields aren't included).
  2. Sort the values themselves, ascending, byte-wise — not the field names.
  3. Join them with a single pipe |.
  4. 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|USD

Secret (hex): a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. Signature:

966f96fb41ec3745aa135c7e770909c911b9ebded7113f1a35e8edea86c1001d

Sorting 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 2xx HTTP response.
  • On anything else, delivery is retried up to 5 more times — 6 attempts in total — with backoff 1m → 5m → 30m → 2h → 6h between 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 (COMPLETED outranks everything; CREATED is 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 2xx response 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 same id + status.
  • Genuinely different statuses for the same payin. PROCESSING and then COMPLETED for the same id isn'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.

On this page