Webhook events

Webhooks deliver order snapshots for selected lifecycle events. Registration, signatures, retries, and deduplication are on Order status.

Events

order.processing: processing started or resumed.
order.confirming: awaiting source confirmations.
order.bridging: crossing chains.
order.swapping: swap executing.
order.awaiting_approval: pending offer or review.
order.refunding: refund underway.
order.delivering: delivery underway.
order.completed: delivered.
order.failed: failure; inspect data.error.
order.unfulfilled: deposit replaced or unconfirmed.
order.refunded: refund confirmed.
order.superseded: successor link advanced.
order.recovery_required: operator release or refund decision needed.

Recovery events go only to /v1/webhooks/recovery subscriptions. Their data can carry status: "processing" with reviewStatus of pending_review or blocked_wallet. A review hold is not a ZeroConf offer. Ordinary paused, expired, and Lightning deposit-timeout transitions emit no webhook. State normalization to processing does not imply an event. Reconcile through status polling.

Envelope

{ "event": "order.completed", "timestamp": "2026-09-10T18:04:12.318Z", "data": { } }

Payload fields

data is the event-time order snapshot. Amounts are integer strings in smallest units; timestamps are ISO 8601. This example shows selected fields, not a complete schema. Optional fields may be omitted rather than null. An order.completed event for 50 USDC on Base delivered as BTC on Spark:

{
  "event": "order.completed",
  "timestamp": "2026-09-10T18:04:12.318Z",
  "data": {
    "id": "ord_01j7qm3x8k9v2n4p6r8t0w2y4a",
    "type": "order",
    "status": "completed",
    "quoteId": "q_01j7qm2r5d7f9h1k3m5p7s9v1x",
    "amountIn": "50000000",
    "amountOut": "45120",
    "feeBps": 5,
    "feeAmount": "25000",
    "slippageBps": 50,
    "source": {
      "chain": "base",
      "asset": "USDC",
      "address": "0x3f1b9c2d4e5f60718293a4b5c6d7e8f901234567",
      "txHash": "0x9a8b7c6d5e4f30211203a4b5c6d7e8f9012345678901234567890abcdef12345",
      "sweepTxHash": null
    },
    "destination": {
      "chain": "spark",
      "asset": "BTC",
      "address": "sp1pgss9x2k4m6n8q0s2u4w6y8a0c2e4g6i8k0m2o4q6s8u0w2y4a6c8e0g2i4k",
      "txHash": "5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
    },
    "depositAddress": "0x7d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e",
    "recipientAddress": "sp1pgss9x2k4m6n8q0s2u4w6y8a0c2e4g6i8k0m2o4q6s8u0w2y4a6c8e0g2i4k",
    "flashnetRequestId": "req_01j7qm3y1a2b3c4d5e6f7g8h9j",
    "sparkTxHash": "5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "refund": { "asset": null, "amount": null, "txHash": null },
    "error": null,
    "createdAt": "2026-09-10T18:02:31.004Z",
    "updatedAt": "2026-09-10T18:04:12.318Z",
    "completedAt": "2026-09-10T18:04:12.318Z"
  }
}

Notes on the fields that need them:

amountOut is null before completion. destination.txHash records delivery; refund is always an object with nullable fields.
feeAmount is in feeAsset units and reads “0” for invoice-billed partners.
quoteId is null for legacy address deposits.
feePlan and feePayouts are present when the order carries app or affiliate fees. Each payout entry has a role (app_fee, recipient_payout, platform_fee, or fee_custody) and a leg (full or holdback; instant appears only on historical multi-leg records).
amountFiatUsd, amountFiatCurrency, and spotUsdPerBtc appear on orders created with a USD amount.
zeroconfOffer is the Bitcoin 0-conf offer; see ZeroConf. error.code values are in Errors.
supersededByOperationId points to the successor after an RBF-replaced deposit; recoveredFromOperationId points back. Both are omitted when absent.
Dedupe on the tuple of data.id, event, and data.updatedAt.

Get started

Endpoints

Events

Envelope

Payload fields

​Events

​Envelope

​Payload fields

Events

Envelope

Payload fields