Receiving Deliveries

Everything a receiving endpoint has to handle: how to tell a genuine delivery from a forged one, which events arrive, and what the delivery contract does not guarantee.

One subscription per entity

A subscription is registered per action, not per status. One withdrawal subscription delivers every status of every payout — processing, done, postponed, rejected and aml_rejected. You never register per status.

Which statuses fire

Entity	Delivers on
deposit	every status change, including aml_processing and processing
withdrawal	every status change, including processing
order	every state except wait
trade	each fill
market	a change to a market

So a receiver must expect intermediate statuses, not only final ones. The single exception in the other direction is an order being accepted: there is no wait delivery, so the response to Create Order is the only record that the order exists.

Authenticating a delivery

The token you registered is sent on every request, in two headers at once:

Webhook-Token: YOUR_WEBHOOK_TOKEN
Authorization: Bearer YOUR_WEBHOOK_TOKEN

If your endpoint is configured for basic auth, the second header is Authorization: Basic base64(username:token) instead.

Compare the token to the one you registered, on every request, and reject anything that does not match.

EXAMPLE DELIVERY — WITHDRAWAL

{
  "id": 19239,
  "uuid": "631aafb95cef-4f55-a699-e9aaff9381a4",
  "client_withdrawal_id": null,
  "member_id": 9663,
  "asset_id": "usdt",
  "dchain_id": "trc20usdt",
  "amount": "20.0",
  "fee": "0.0",
  "status": "processing",
  "tx_id": null,
  "destination": "TB8cX7Jnwy8kuzPEvJ7zEsZhUszq66VPC6",
  "destination_tag": null,
  "operation_type": "ON_CHAIN",
  "created_at": "2026-07-24T09:46:20.761Z",
  "updated_at": "2026-07-24T09:46:21.481Z"
}

EXAMPLE DELIVERY — DEPOSIT

{
  "id": 95,
  "member_id": 27,
  "deposit_address_id": 92,
  "asset_id": "usdt",
  "dchain_id": "trc20usdt",
  "amount": "8.9",
  "fee": "1.1",
  "status": "done",
  "tx_id": "226f48af6519b893a2f7c27af6498582c5c6d8f697a4c5a895ebc6e459779de9",
  "address": "TYNoh8n74Bd4rrZaYyfYJZikvfNDQkpYfX",
  "address_tag": null,
  "operation_type": "ON_CHAIN",
  "created_at": "2026-07-21T12:16:23.000Z",
  "updated_at": "2026-07-21T12:17:25.000Z"
}

How to trust a delivery

The token in the headers is what identifies a delivery as genuine, so two rules apply:

1. Serve the endpoint over HTTPS only, so the token is never sent in cleartext.
2. Re-read the object through the API before anything irreversible. Treat a delivery as a signal that something changed, and the API as the record of what it changed to.

No retries, and no ordering

Delivery is asynchronous, has no sequence number, and is not retried automatically. Two things follow, and both will happen in production:

• A delivery can be lost. If your endpoint is down or answers slowly, that event is gone — nothing re-sends it. Reconcile by polling the API for anything that matters.
• Deliveries can arrive out of order. processing can land after done for the same object.

So the receiver must be idempotent and must apply state by comparing updated_at, not by arrival order:

on delivery:
  existing = lookup(payload.id)
  if existing and existing.updated_at >= payload.updated_at:
      ignore            # this is older news than what we already have
  else:
      apply(payload)

Writing the handler as "set status = payload.status" instead will eventually walk a customer's payout backwards from done to processing.