What event types are emitted?
Most events correspond to a partner-visibleorder.status transition, where the event field in the payload is order.<status>. One event, order.superseded, is not a status change — see Recovered (superseded) orders.
What is the payload shape?
Every webhook POST contains aWebhookEvent envelope. The data field is a full order snapshot at the moment the event was emitted.
Always present
Present on exact-out quotes
Recovered (superseded) orders
When a Bitcoin deposit is replaced — for example RBF’d or re-broadcast so the original transaction never confirms — the first order can endunfulfilled, and the confirmed replacement is picked up as a new order that takes over the swap. The two orders are linked so you can follow a customer from the dead order to the one that actually runs.
The dedicated
order.superseded event fires on the original order each time its link is set or advanced to a new successor, carrying data.supersededByOperationId. The successor’s own status events carry data.recoveredFromOperationId. Both ids are also present on the REST order responses (GET /v1/orchestration/status, /order, /history).
The successor is created from a replacement deposit that may still be confirming, so it can be in flight when
order.superseded arrives. Treat supersededByOperationId as “where the deposit went,” not proof of delivery — open or poll the successor for its status. If that successor is itself replaced before delivering, the link advances and order.superseded fires again with the newer id. Webhook delivery is not ordered (fire-and-forget with retries), so do not treat the last-arrived event as current: reconcile by the payload timestamp, or re-read the order (GET /v1/orchestration/status) and trust its supersededByOperationId.Present on Bitcoin L1 deposits with ZeroConf
data.zeroconfOffer carries the offer object. The schema is owned by ZeroConf offer fields; webhook payloads use the same projection as the status API.
Webhook-specific notes:
- The offer appears on every event’s order snapshot while it is stored on the order, not only on
order.awaiting_approval. - Act when the event is
order.awaiting_approvalanddata.zeroconfOffer.statusis"pending". Later events carry the resolved offer (accepted,declined,expired, orconfirmed) for audit.
Present when app/affiliate fees are configured
feePayouts populates incrementally as payout legs execute. Early events may have an empty entries array.
Which status transitions emit events?
The event is determined by the status the order lands on: every partner-visible transition into a status below emitsorder.<status>, regardless of the status it came from. The allowed transitions themselves are defined in Order Lifecycle; this table maps the destination status to the event your handler receives.
Statuses outside this table emit nothing:
pausedemits no event and is masked: while an order is paused for operator review, status snapshots and webhook payloads reportprocessing. If the order resumes, later public transitions emit normally. If it is condemned after review, the webhook isorder.failed.expiredemits no event. It is visible through status polling and SSE only.
unfulfilled is terminal but can resume on a late deposit. When it resumes, webhooks fire again for the statuses the order moves through (confirming, swapping, delivering, completed). completed, failed, and refunded emit no further events.