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.
Webhooks deliver public order status changes as signed HTTP POST requests. For signature verification, retry logic, and delivery semantics, see Webhooks.
What event types are emitted?
Each event corresponds to a partner-visible order.status transition. The event field in the payload is order.<status>.
| Event | Trigger | Key fields |
|---|
order.processing | Order created, deposit detected | amountIn, source, depositAddress |
order.confirming | Waiting for on-chain confirmation (Bitcoin L1) | source.txHash |
order.bridging | Cross-chain bridge initiated | source, destination |
order.swapping | Flashnet swap executing | amountIn, feeAmount |
order.awaiting_approval | ZeroConf offer requires partner action | zeroconfOffer |
order.refunding | Refund initiated (market moved past slippage, exact-out could not be satisfied, or stale-quote deposit) | refund, error |
order.delivering | Final delivery to destination address in progress | destination, amountOut |
order.completed | Order finished, funds delivered | amountOut, destination.txHash, completedAt |
order.failed | Terminal failure | error |
order.unfulfilled | Order cannot proceed (e.g. deposit not received within window) | error |
order.refunded | Refund delivered | refund.txHash, refund.amount |
What is the payload shape?
Every webhook POST contains a WebhookEvent envelope. The data field is a full order snapshot at the moment the event was emitted.
Always present
| Field | Type | Notes |
|---|
event | string | order.<status> |
timestamp | string | ISO 8601 delivery timestamp |
data.id | string | Order ID (ord_...) |
data.type | string | Always "order" |
data.status | string | Partner-visible order status. Internal paused orders are reported as processing. |
data.quoteId | string | null | Quote ID. null for accumulation/liquidation address deposits. |
data.amountIn | string | Input amount in smallest units |
data.amountOut | string | null | Output amount. null until delivery. |
data.feeBps | number | Platform fee rate |
data.feeAmount | string | Platform fee in smallest units |
data.slippageBps | number | Slippage tolerance |
data.source.chain | string | Source chain |
data.source.asset | string | Source asset |
data.source.address | string | null | Sender address when known |
data.source.txHash | string | null | Source transaction hash |
data.source.sweepTxHash | string | null | Sweep transaction hash (accumulation/liquidation flows) |
data.destination.chain | string | Destination chain |
data.destination.asset | string | Destination asset |
data.destination.address | string | Recipient address |
data.destination.txHash | string | null | Delivery transaction hash. null until delivered. |
data.depositAddress | string | Deposit address from the quote |
data.recipientAddress | string | Recipient address on destination chain |
data.flashnetRequestId | string | null | Flashnet swap request ID when a swap has executed |
data.sparkTxHash | string | null | Spark transfer or withdrawal hash |
data.refund.asset | string | null | Refund asset |
data.refund.amount | string | null | Refund amount |
data.refund.txHash | string | null | Refund transaction hash |
data.error.code | string | null | Error code when status requires action or has failed |
data.error.message | string | null | Human-readable error description |
data.createdAt | string | ISO 8601 order creation time |
data.updatedAt | string | ISO 8601 last update time |
data.completedAt | string | null | ISO 8601 completion time. null until completed. |
Present on exact-out quotes
| Field | Type | Notes |
|---|
data.paymentIntent.version | number | Always 1 |
data.paymentIntent.amountMode | string | "exact_out" |
data.paymentIntent.targetAmountOut | string | Requested output amount |
data.paymentIntent.requiredAmountIn | string | Required input |
data.paymentIntent.maxAcceptedAmountIn | string | Maximum accepted input |
data.paymentIntent.inputBufferBps | number | Input buffer tolerance |
data.paymentIntent.actualAmountIn | string | null | Actual deposited amount |
data.paymentIntent.refundAddress | string | Refund address for overpayment |
data.paymentIntent.exactOutExecution | string | "strict" |
Present on Bitcoin L1 deposits with ZeroConf
| Field | Type | Notes |
|---|
data.zeroconfOffer.version | number | Always 1 |
data.zeroconfOffer.status | string | "pending", "accepted", "declined", "expired", or "confirmed" |
data.zeroconfOffer.quoteId | string | ZeroConf quote ID (zc_...) |
data.zeroconfOffer.sparkAddress | string | Spark address for instant credit |
data.zeroconfOffer.txid | string | Bitcoin transaction ID |
data.zeroconfOffer.vout | number | Transaction output index |
data.zeroconfOffer.depositSats | string | Total BTC deposited (sats) |
data.zeroconfOffer.instantSats | string | Amount credited instantly on acceptance |
data.zeroconfOffer.holdbackSats | string | Amount held until on-chain confirmation |
data.zeroconfOffer.feeSats | string | ZeroConf fee (sats) |
data.zeroconfOffer.confirmationProbability | number | Estimated confirmation probability |
data.zeroconfOffer.expiresAt | string | ISO 8601 offer expiry |
data.zeroconfOffer.offeredAt | string | ISO 8601 when the offer was generated |
data.zeroconfOffer.resolvedAt | string | null | ISO 8601 resolution time. null while pending. |
| Field | Type | Notes |
|---|
data.feePlan.version | number | Always 1 |
data.feePlan.settlementChain | string | Chain where fees settle (e.g. "solana") |
data.feePlan.settlementAsset | string | Asset used for fee settlement (e.g. "USDC") |
data.feePlan.appFees | AppFee[] | Array of fee entries |
data.feePlan.appFees[*].affiliateId | string | undefined | Present for registry-based entries |
data.feePlan.appFees[*].recipient | string | Payout address |
data.feePlan.appFees[*].feeBps | number | Fee rate in basis points |
data.feePayouts.version | number | Always 1 |
data.feePayouts.entries | FeePayoutEntry[] | Array of payout leg records |
data.feePayouts.entries[*].idempotencyKey | string | Unique payout key |
data.feePayouts.entries[*].leg | string | "full", "instant", or "holdback" |
data.feePayouts.entries[*].chain | string | Payout chain |
data.feePayouts.entries[*].role | string | "app_fee" or "recipient_payout" |
data.feePayouts.entries[*].affiliateId | string | undefined | Present for registry-based app-fee entries |
data.feePayouts.entries[*].recipient | string | Payout address |
data.feePayouts.entries[*].feeBps | number | null | Fee rate. null for recipient_payout. |
data.feePayouts.entries[*].amount | string | Gross fee amount |
data.feePayouts.entries[*].platformCutAmount | string | null | Flashnet’s 20% cut. null for recipient_payout. |
data.feePayouts.entries[*].recipientAmount | string | null | 80% paid to recipient. null for recipient_payout. |
data.feePayouts.entries[*].txHash | string | Payout transaction hash |
data.feePayouts.entries[*].recordedAt | string | ISO 8601 when the payout was recorded |
feePayouts populates incrementally as payout legs execute. Early events may have an empty entries array.
Which status transitions emit events?
Each public status transition emits a single webhook event. The order lifecycle defines valid transitions; this table maps partner-visible transitions to the events your handler receives.
Internal paused transitions do not emit order.paused. While an order is paused, status snapshots show processing. If the order resumes, later public transitions emit normally. If it is condemned after review, the webhook is order.failed.
| From | To | Event emitted |
|---|
| (new) | processing | order.processing |
processing | confirming | order.confirming |
processing | bridging | order.bridging |
processing | swapping | order.swapping |
processing | awaiting_approval | order.awaiting_approval (ZeroConf offer only) |
processing | refunding | order.refunding |
processing | delivering | order.delivering |
processing | completed | order.completed |
processing | failed | order.failed |
processing | unfulfilled | order.unfulfilled |
processing | refunded | order.refunded |
confirming | bridging | order.bridging |
confirming | swapping | order.swapping |
confirming | refunding | order.refunding |
confirming | delivering | order.delivering |
confirming | completed | order.completed |
confirming | failed | order.failed |
confirming | refunded | order.refunded |
bridging | swapping | order.swapping |
bridging | delivering | order.delivering |
bridging | completed | order.completed |
bridging | failed | order.failed |
bridging | refunded | order.refunded |
swapping | awaiting_approval | order.awaiting_approval |
swapping | refunding | order.refunding |
swapping | bridging | order.bridging |
swapping | delivering | order.delivering |
swapping | completed | order.completed |
swapping | failed | order.failed |
swapping | refunded | order.refunded |
awaiting_approval | processing | order.processing |
awaiting_approval | confirming | order.confirming |
awaiting_approval | swapping | order.swapping |
awaiting_approval | refunding | order.refunding |
awaiting_approval | failed | order.failed |
awaiting_approval | refunded | order.refunded |
delivering | confirming | order.confirming |
delivering | refunding | order.refunding |
delivering | completed | order.completed |
delivering | failed | order.failed |
delivering | refunded | order.refunded |
unfulfilled | confirming | order.confirming |
unfulfilled | bridging | order.bridging |
unfulfilled | swapping | order.swapping |
unfulfilled | delivering | order.delivering |
unfulfilled | completed | order.completed |
refunding | refunded | order.refunded |
refunding | failed | order.failed |
completed, failed, expired, refunded) emit no further events. expired is visible through status polling and SSE, but is not emitted as a webhook event in the current webhook event set. unfulfilled stops automatic execution, but can resume if a late deposit arrives.
See Order Lifecycle for the full state machine, including transition conditions and what each status means.
