Skip to main content
Webhooks deliver 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 an order.status transition. The event field in the payload is order.<status>.
EventTriggerKey fields
order.processingOrder created, deposit detectedamountIn, source, depositAddress
order.confirmingWaiting for on-chain confirmation (Bitcoin L1)source.txHash
order.bridgingCross-chain bridge initiatedsource, destination
order.swappingFlashnet swap executingamountIn, feeAmount
order.awaiting_approvalRepricing or ZeroConf offer requires partner actionreprice, zeroconfOffer
order.refundingRefund initiated after rejected repricerefund
order.deliveringFinal delivery to destination address in progressdestination, amountOut
order.completedOrder finished, funds deliveredamountOut, destination.txHash, completedAt
order.failedTerminal failureerror
order.expiredTerminal timeout (e.g. Lightning invoice expired without payment)error
order.unfulfilledOrder cannot proceed (e.g. deposit not received within window)error
order.refundedRefund deliveredrefund.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

FieldTypeNotes
eventstringorder.<status>
timestampstringISO 8601 delivery timestamp
data.idstringOrder ID (ord_...)
data.typestringAlways "order"
data.statusstringCurrent order status
data.quoteIdstring | nullQuote ID. null for accumulation/liquidation address deposits.
data.amountInstringInput amount in smallest units
data.amountOutstring | nullOutput amount. null until delivery.
data.feeBpsnumberPlatform fee rate
data.feeAmountstringPlatform fee in smallest units
data.slippageBpsnumberSlippage tolerance
data.source.chainstringSource chain
data.source.assetstringSource asset
data.source.addressstring | nullSender address when known
data.source.txHashstring | nullSource transaction hash
data.source.sweepTxHashstring | nullSweep transaction hash (accumulation/liquidation flows)
data.destination.chainstringDestination chain
data.destination.assetstringDestination asset
data.destination.addressstringRecipient address
data.destination.txHashstring | nullDelivery transaction hash. null until delivered.
data.depositAddressstringDeposit address from the quote
data.recipientAddressstringRecipient address on destination chain
data.flashnetRequestIdstring | nullFlashnet swap request ID when a swap has executed
data.sparkTxHashstring | nullSpark transfer or withdrawal hash
data.refund.assetstring | nullRefund asset
data.refund.amountstring | nullRefund amount
data.refund.txHashstring | nullRefund transaction hash
data.error.codestring | nullError code when status requires action or has failed
data.error.messagestring | nullHuman-readable error description
data.createdAtstringISO 8601 order creation time
data.updatedAtstringISO 8601 last update time
data.completedAtstring | nullISO 8601 completion time. null until completed.

​
Present on price-locked or exact-out quotes

FieldTypeNotes
data.priceLock.versionnumberAlways 1
data.priceLock.modestring"approval_required" or "strict_requote"
data.priceLock.amountInstringQuoted input amount
data.priceLock.quotedAmountOutstringOriginally quoted output
data.priceLock.lockedMinAmountOutstringGuaranteed minimum output
data.priceLock.slippageBpsnumberSlippage at lock time
data.priceLock.createdAtstringISO 8601
data.priceLock.expiresAtstringISO 8601
data.reprice.versionnumberAlways 1
data.reprice.statusstring"awaiting_approval", "approved", "rejected", or "refunded"
data.reprice.previousLockedMinAmountOutstringPrevious locked minimum
data.reprice.proposedMinAmountOutstringProposed new minimum
data.reprice.latestExpectedAmountOutstringCurrent expected output at live rates
data.reprice.requestedAtstringISO 8601
data.reprice.resolvedAtstring | nullISO 8601. null while pending.
data.reprice.reasonstringWhy repricing was triggered (e.g. "insufficient_input")
data.paymentIntent.versionnumberAlways 1
data.paymentIntent.amountModestring"exact_out"
data.paymentIntent.targetAmountOutstringRequested output amount
data.paymentIntent.requiredAmountInstringRequired input
data.paymentIntent.maxAcceptedAmountInstringMaximum accepted input
data.paymentIntent.inputBufferBpsnumberInput buffer tolerance
data.paymentIntent.actualAmountInstring | nullActual deposited amount
data.paymentIntent.refundAddressstringRefund address for overpayment
data.paymentIntent.exactOutExecutionstring"strict"

​
Present on Bitcoin L1 deposits with ZeroConf

FieldTypeNotes
data.zeroconfOffer.versionnumberAlways 1
data.zeroconfOffer.statusstring"pending", "accepted", "declined", "expired", or "confirmed"
data.zeroconfOffer.quoteIdstringZeroConf quote ID (zc_...)
data.zeroconfOffer.sparkAddressstringSpark address for instant credit
data.zeroconfOffer.txidstringBitcoin transaction ID
data.zeroconfOffer.voutnumberTransaction output index
data.zeroconfOffer.depositSatsstringTotal BTC deposited (sats)
data.zeroconfOffer.instantSatsstringAmount credited instantly on acceptance
data.zeroconfOffer.holdbackSatsstringAmount held until on-chain confirmation
data.zeroconfOffer.feeSatsstringZeroConf fee (sats)
data.zeroconfOffer.confirmationProbabilitynumberEstimated confirmation probability
data.zeroconfOffer.expiresAtstringISO 8601 offer expiry
data.zeroconfOffer.offeredAtstringISO 8601 when the offer was generated
data.zeroconfOffer.resolvedAtstring | nullISO 8601 resolution time. null while pending.
See ZeroConf offer fields for the full reference.

​
Present when app/affiliate fees are configured

FieldTypeNotes
data.feePlan.versionnumberAlways 1
data.feePlan.settlementChainstringChain where fees settle (e.g. "solana")
data.feePlan.settlementAssetstringAsset used for fee settlement (e.g. "USDC")
data.feePlan.appFeesAppFee[]Array of fee entries
data.feePlan.appFees[*].affiliateIdstring | undefinedPresent for registry-based entries
data.feePlan.appFees[*].recipientstringPayout address
data.feePlan.appFees[*].feeBpsnumberFee rate in basis points
data.feePayouts.versionnumberAlways 1
data.feePayouts.entriesFeePayoutEntry[]Array of payout leg records
data.feePayouts.entries[*].idempotencyKeystringUnique payout key
data.feePayouts.entries[*].legstring"full", "instant", or "holdback"
data.feePayouts.entries[*].chainstringPayout chain
data.feePayouts.entries[*].rolestring"app_fee" or "recipient_payout"
data.feePayouts.entries[*].affiliateIdstring | undefinedPresent for registry-based app-fee entries
data.feePayouts.entries[*].recipientstringPayout address
data.feePayouts.entries[*].feeBpsnumber | nullFee rate. null for recipient_payout.
data.feePayouts.entries[*].amountstringGross fee amount
data.feePayouts.entries[*].platformCutAmountstring | nullFlashnet’s 20% cut. null for recipient_payout.
data.feePayouts.entries[*].recipientAmountstring | null80% paid to recipient. null for recipient_payout.
data.feePayouts.entries[*].txHashstringPayout transaction hash
data.feePayouts.entries[*].recordedAtstringISO 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 status transition emits a single webhook event. The order lifecycle defines valid transitions; this table maps them to the events your handler receives.
FromToEvent emitted
(new)processingorder.processing
processingconfirmingorder.confirming
processingbridgingorder.bridging
processingswappingorder.swapping
processingawaiting_approvalorder.awaiting_approval
processingrefundingorder.refunding
processingdeliveringorder.delivering
processingcompletedorder.completed
processingfailedorder.failed
processingexpiredorder.expired
processingunfulfilledorder.unfulfilled
processingrefundedorder.refunded
confirmingbridgingorder.bridging
confirmingswappingorder.swapping
confirmingrefundingorder.refunding
confirmingdeliveringorder.delivering
confirmingcompletedorder.completed
confirmingfailedorder.failed
confirmingexpiredorder.expired
confirmingrefundedorder.refunded
bridgingswappingorder.swapping
bridgingdeliveringorder.delivering
bridgingcompletedorder.completed
bridgingfailedorder.failed
bridgingrefundedorder.refunded
swappingawaiting_approvalorder.awaiting_approval
swappingrefundingorder.refunding
swappingbridgingorder.bridging
swappingdeliveringorder.delivering
swappingcompletedorder.completed
swappingfailedorder.failed
swappingrefundedorder.refunded
awaiting_approvalprocessingorder.processing
awaiting_approvalconfirmingorder.confirming
awaiting_approvalswappingorder.swapping
awaiting_approvalrefundingorder.refunding
awaiting_approvalfailedorder.failed
awaiting_approvalrefundedorder.refunded
deliveringconfirmingorder.confirming
deliveringrefundingorder.refunding
deliveringcompletedorder.completed
deliveringfailedorder.failed
deliveringrefundedorder.refunded
unfulfilledconfirmingorder.confirming
unfulfilledbridgingorder.bridging
unfulfilledswappingorder.swapping
unfulfilleddeliveringorder.delivering
unfulfilledcompletedorder.completed
refundingrefundedorder.refunded
refundingfailedorder.failed
Terminal statuses (completed, failed, expired, refunded) emit no further events. unfulfilled is non-terminal: orders in this status can resume if a deposit arrives late. See Order Lifecycle for the full state machine, including transition conditions and what each status means.