> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashnet.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> Events and payloads

Webhooks deliver order snapshots for selected lifecycle events. Registration, signatures, retries, and deduplication are on [Order status](/orchestra/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

```json theme={null}
{ "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:

```json theme={null}
{
  "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](/orchestra/zeroconf). `error.code` values are in [Errors](/api/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`.