Skip to main content

Webhook Lifecycle Flows

This page describes the sequence of webhooks you will receive for common transaction flows.

Understanding these sequences will help you build robust integrations and properly track the state of customer transactions.

info

Webhook delivery order is not guaranteed. Always use EventVersion to determine the latest state for any given resource.

Status Values

All webhooks use these status values:

StatusMeaning
PendingProcessing in progress
SettledSuccessfully completed
FailedDid not complete; check for refund information

Transitions: PendingSettled OR PendingFailed


Bank OnRamp (Fiat Deposit → Stablecoin Payout)

When a customer deposits fiat via a Virtual Account (VIBAN) and it triggers a stablecoin purchase and on-chain payout, you will receive at least the following webhooks.

Customer deposits fiat to VIBAN


┌─────────────────────────────────────────┐
│ 1. FiatDeposit │
│ Status: "Pending" │
│ ─────────────────────────────────────── │
│ Bank confirmation received. │
│ │
│ Note: May not appear in Sandbox due to │
│ relaxed risk rules. │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 2. FiatDeposit │
│ Status: "Settled" │
│ ─────────────────────────────────────── │
│ Risk/KYT approved the deposit. │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 3. Transaction (PayIn) │
│ Status: "Pending" │
│ Direction: "In" │
│ Network: "OffNetwork" │
│ ─────────────────────────────────────── │
│ Fiat converted to stablecoin. │
│ Fees calculated (see Breakdown). │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 4. Transaction (PayOut) │
│ Status: "Pending" │
│ Direction: "Out" │
│ Network: "<chain name>" │
│ ─────────────────────────────────────── │
│ On-chain payout initiated. │
│ Network fees deducted. │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 5. Transaction (PayIn) │
│ Status: "Settled" │
│ Direction: "In" │
│ ─────────────────────────────────────── │
│ Internal ledger credit confirmed. │
│ (Fast—KYT already done at FiatDeposit) │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 6. Transaction (PayOut) │
│ Status: "Settled" │
│ Direction: "Out" │
│ ─────────────────────────────────────── │
│ On-chain transaction confirmed. │
│ PublicID contains tx hash. │
│ │
│ ✓ FINAL CONFIRMATION │
└─────────────────────────────────────────┘

Summary

#EventTypeStatusDirectionNetworkMeaning
1FiatDepositPendingBank confirmation received
2FiatDepositSettledRisk/KYT approved
3TransactionPendingInOffNetworkFiat converted to stablecoin
4TransactionPendingOutChain nameOn-chain payout initiated
5TransactionSettledInOffNetworkInternal ledger credit confirmed
6TransactionSettledOutChain nameOn-chain tx confirmed ✓

Example Payloads

Webhook 1 — FiatDeposit (Pending)

{
"Data": {
"Created": "2025-12-04T12:41:06Z",
"CustomerID": "ronaldo-noah-203",
"FiatAmount": "100",
"FiatCurrency": "EUR",
"ID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"PaymentMethodID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodType": "BankSepa",
"Refunds": [],
"Sender": {
"Details": {
"AccountNumber": "MT60SEOUUR41270441818820",
"Type": "FiatPaymentMethodBankDisplay"
}
},
"Status": "Pending"
},
"EventType": "FiatDeposit",
"EventVersion": 1764852066045,
"Occurred": "2025-12-04T12:41:06Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Webhook 2 — FiatDeposit (Settled)

{
"Data": {
"Created": "2025-12-04T12:41:06Z",
"CustomerID": "ronaldo-noah-203",
"FiatAmount": "100",
"FiatCurrency": "EUR",
"ID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"PaymentMethodID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodType": "BankSepa",
"Refunds": [],
"Sender": {
"Details": {
"AccountNumber": "MT60SEOUUR41270441818820",
"Type": "FiatPaymentMethodBankDisplay"
}
},
"Status": "Settled"
},
"EventType": "FiatDeposit",
"EventVersion": 1764852066045,
"Occurred": "2025-12-04T12:41:06Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Webhook 3 — Transaction PayIn (Pending)

{
"Data": {
"Amount": "111.979797",
"Breakdown": [
{ "Amount": "1.13111", "Type": "ChannelFee" },
{ "Amount": "111.979797", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:12Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "In",
"FiatPayment": {
"Amount": "100",
"FeeAmount": "1",
"FiatCurrency": "EUR",
"FiatDepositID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"Rate": "0.8840880389680685"
},
"FiatPaymentMethod": {
"Country": "MT",
"CustomerID": "ronaldo-noah-203",
"DisplayDetails": {
"AccountNumber": "MT60SEOUUR41270441818820",
"BankCode": "CFTEMTM1XXX",
"Type": "FiatPaymentMethodBankDisplay"
},
"ID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodCategory": "Bank"
},
"ID": "4068d70e-c31d-5e3b-959a-f27ea3cc5e1e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764852072100,
"Occurred": "2025-12-04T12:41:12Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Webhook 4 — Transaction PayOut (Pending)

{
"Data": {
"Amount": "107.683104",
"Breakdown": [
{ "Amount": "4.296693", "Type": "NetworkFee" },
{ "Amount": "107.683104", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:14Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "Out",
"ID": "fee2b2a6-0da2-5473-a6a8-eac39cb279d9",
"Network": "EthereumTestSepolia",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764852074748,
"Occurred": "2025-12-04T12:41:14Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Webhook 5 — Transaction PayIn (Settled)

{
"Data": {
"Amount": "111.979797",
"Breakdown": [
{ "Amount": "1.13111", "Type": "ChannelFee" },
{ "Amount": "111.979797", "Type": "Remaining" }
],
"Created": "2025-12-04T12:41:12Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "In",
"FiatPayment": {
"Amount": "100",
"FeeAmount": "1",
"FiatCurrency": "EUR",
"FiatDepositID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"Rate": "0.8840880389680685"
},
"FiatPaymentMethod": {
"Country": "MT",
"CustomerID": "ronaldo-noah-203",
"DisplayDetails": {
"AccountNumber": "MT60SEOUUR41270441818820",
"BankCode": "CFTEMTM1XXX",
"Type": "FiatPaymentMethodBankDisplay"
},
"ID": "Bank/Sepa/EUR/CFTEMTM1XXX/MT60SEOUUR41270441818820/ronaldo-noah-203",
"PaymentMethodCategory": "Bank"
},
"ID": "4068d70e-c31d-5e3b-959a-f27ea3cc5e1e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764852079016,
"Occurred": "2025-12-04T12:41:19Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Webhook 6 — Transaction PayOut (Settled)

{
"Data": {
"Amount": "107.683104",
"Breakdown": [
{ "Amount": "4.296693", "Type": "NetworkFee" },
{ "Amount": "107.683104", "Type": "Remaining" }
],
"Created": "2025-12-04T13:00:17Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "ronaldo-noah-203",
"Direction": "Out",
"ID": "fee2b2a6-0da2-5473-a6a8-eac39cb279d9",
"Network": "EthereumTestSepolia",
"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
},
"PublicID": "mockFireblocks_0158a83c8496379ec8bdd183eb92d9d06576a594df5dcef4e269ccfc6bb4617f",
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764853243442,
"Occurred": "2025-12-04T13:00:44Z",
"UserID": "ory|a642bfdd-dd6e-4c75-943a-3f10734b97f1"
}

Crypto OffRamp (On-chain Deposit → Fiat Payout)

When a customer deposits crypto on-chain and it triggers a fiat payout to a beneficiary, you will receive at least the following webhooks.

Customer sends crypto to deposit address


┌─────────────────────────────────────────┐
│ 1. Transaction (Crypto Deposit) │
│ Status: "Pending" │
│ Direction: "In" │
│ Network: "<chain name>" │
│ ─────────────────────────────────────── │
│ Crypto deposit received at destination │
│ address. PublicID contains tx hash. │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 2. Transaction (Crypto Deposit) │
│ Status: "Settled" │
│ Direction: "In" │
│ ─────────────────────────────────────── │
│ Risk analysis passed. │
│ Crypto deposit confirmed. │
│ │
│ ✓ FUNDS COMMITTED │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 3. Transaction (Fiat Payout) │
│ Status: "Pending" │
│ Direction: "Out" │
│ Network: "OffNetwork" │
│ ─────────────────────────────────────── │
│ Fiat payout initiated to beneficiary. │
└─────────────────────────────────────────┘


┌─────────────────────────────────────────┐
│ 4. Transaction (Fiat Payout) │
│ Status: "Settled" │
│ Direction: "Out" │
│ ─────────────────────────────────────── │
│ Bank accepted the payment. │
│ Beneficiary receives funds per channel │
│ settlement time. │
│ │
│ ✓ FINAL CONFIRMATION │
└─────────────────────────────────────────┘

Summary

#EventTypeStatusDirectionNetworkMeaning
1TransactionPendingInChain nameCrypto deposit received
2TransactionSettledInChain nameRisk passed, deposit confirmed
3TransactionPendingOutOffNetworkFiat payout initiated
4TransactionSettledOutOffNetworkBank accepted payment ✓

Example Payloads

Webhook 1 — Crypto Deposit (Pending)

{
"Data": {
"Amount": "500",
"Created": "2025-12-04T13:52:04Z",
"CryptoCurrency": "USDC_TEST",
"Direction": "In",
"ID": "6c276fc4-d118-11f0-89ce-aad3bcb4fac3",
"Network": "PolygonTestAmoy",
"PublicID": "mockFireblocks_7ac471fc15106e7608903ae03c925109a7111d47a7913ea74c72df417cee863c",
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764856327809,
"Occurred": "2025-12-04T13:52:08Z",
"UserID": "ory|b41988ec-24d7-4b16-8cba-7942bd140ff6"
}

Webhook 2 — Crypto Deposit (Settled)

{
"Data": {
"Amount": "500",
"Created": "2025-12-04T13:52:04Z",
"CryptoCurrency": "USDC_TEST",
"Direction": "In",
"ID": "6c276fc4-d118-11f0-89ce-aad3bcb4fac3",
"Network": "PolygonTestAmoy",
"PublicID": "mockFireblocks_7ac471fc15106e7608903ae03c925109a7111d47a7913ea74c72df417cee863c",
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764856336008,
"Occurred": "2025-12-04T13:52:16Z",
"UserID": "ory|b41988ec-24d7-4b16-8cba-7942bd140ff6"
}

Webhook 3 — Fiat Payout (Pending)

{
"Data": {
"Created": "2025-12-04T13:52:20Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "74508010-c30b-4c58-a94d-591c281d8630",
"Direction": "Out",
"FiatPayment": {
"Amount": "500",
"FeeAmount": "15.58",
"FiatCurrency": "BRL"
},
"FiatPaymentMethod": {
"Country": "BR",
"CustomerID": "74508010-c30b-4c58-a94d-591c281d8630",
"DisplayDetails": {
"Identifier": "11184369623",
"IdentifierType": "TaxID",
"Type": "FiatPaymentMethodIdentifierDisplay"
},
"ID": "Identifier/Pix/BRL/TaxID/bc85f444-7ef6-53c9-94fc-b7dcc3d8a209/74508010-c30b-4c58-a94d-591c281d8630",
"PaymentMethodCategory": "Identifier"
},
"ID": "0ee0ed7a-57eb-5818-bd11-67cccd940e3e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "6c276fc4-d118-11f0-89ce-aad3bcb4fac3",
"RuleID": "a3a1e805-0de0-540f-bdef-e6d948f6c89f"
},
"Status": "Pending"
},
"EventType": "Transaction",
"EventVersion": 1764856340977,
"Occurred": "2025-12-04T13:52:21Z",
"UserID": "ory|b41988ec-24d7-4b16-8cba-7942bd140ff6"
}

Webhook 4 — Fiat Payout (Settled)

{
"Data": {
"Amount": "99.370156",
"Created": "2025-12-04T13:52:57Z",
"CryptoCurrency": "USDC_TEST",
"CustomerID": "74508010-c30b-4c58-a94d-591c281d8630",
"Direction": "Out",
"FiatPayment": {
"Amount": "500",
"FeeAmount": "15.58",
"FiatCurrency": "BRL",
"Rate": "5.18847933"
},
"FiatPaymentMethod": {
"Country": "BR",
"CustomerID": "74508010-c30b-4c58-a94d-591c281d8630",
"DisplayDetails": {
"Identifier": "11184369623",
"IdentifierType": "TaxID",
"Type": "FiatPaymentMethodIdentifierDisplay"
},
"ID": "Identifier/Pix/BRL/TaxID/bc85f444-7ef6-53c9-94fc-b7dcc3d8a209/74508010-c30b-4c58-a94d-591c281d8630",
"PaymentMethodCategory": "Identifier"
},
"ID": "0ee0ed7a-57eb-5818-bd11-67cccd940e3e",
"Network": "OffNetwork",
"Orchestration": {
"RuleExecutionID": "6c276fc4-d118-11f0-89ce-aad3bcb4fac3",
"RuleID": "a3a1e805-0de0-540f-bdef-e6d948f6c89f"
},
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764856385061,
"Occurred": "2025-12-04T13:53:06Z",
"UserID": "ory|b41988ec-24d7-4b16-8cba-7942bd140ff6"
}

Crypto OffRamp — Failed Payout (Refund Flow)

When a fiat payout fails, the crypto deposit is automatically refunded to the customer.

Flow

#EventTypeStatusDirectionDescription
1TransactionPendingInCrypto deposit received
2TransactionSettledInCrypto deposit confirmed
3TransactionPendingOutFiat payout initiated
4TransactionFailedOutFiat payout failed
5TransactionSettledInOriginal deposit updated with Refunds array
6TransactionSettledOutRefund withdrawal; contains AdjustmentFor

Refunds Array

When a refund is initiated, the original deposit transaction is updated with a Refunds array. This array can contain multiple entries if retries occurred.

Example — Original deposit updated with Refunds:

{
"Data": {
"Amount": "500",
"Created": "2025-12-04T14:11:12Z",
"CryptoCurrency": "USDC_TEST",
"Direction": "In",
"ID": "1865092c-d11b-11f0-803f-4a01279ab918",
"Network": "PolygonTestAmoy",
"Orchestration": {
"RuleExecutionID": "1865092c-d11b-11f0-803f-4a01279ab918",
"RuleID": "954bb1ac-47b6-58e3-87e6-3f987c030ced"
},
"PublicID": "mockFireblocks_c65f4c37b820cbb0ca3ba29b576b9230e7aa9ace6e6d09f18301df467e054130",
"Refunds": [
{
"Currency": "USDC_TEST",
"RefundID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
"RefundedAmount": "500",
"RequestTime": "2025-12-04T14:11:57Z",
"Status": "Settled"
}
],
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764857544606,
"Occurred": "2025-12-04T14:12:25Z",
"UserID": "ory|5d8fcbdf-115d-4fbe-ae4a-82744c6417d1"
}

AdjustmentFor

The refund withdrawal transaction contains an AdjustmentFor object that links back to the original deposit being refunded.

Example — Refund withdrawal with AdjustmentFor:

{
"Data": {
"AdjustmentFor": {
"AdjustedTransactionID": "1865092c-d11b-11f0-803f-4a01279ab918",
"AdjustmentID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
"Reason": "Refund"
},
"Amount": "500",
"Created": "2025-12-04T14:12:04Z",
"CryptoCurrency": "USDC_TEST",
"Direction": "Out",
"ID": "9fd12df5-e5ca-5e10-90d0-49a03d570f9b",
"Network": "PolygonTestAmoy",
"Orchestration": {
"RuleExecutionID": "1865092c-d11b-11f0-803f-4a01279ab918",
"RuleID": "954bb1ac-47b6-58e3-87e6-3f987c030ced"
},
"PublicID": "mockFireblocks_b47aa72dc194f06cfe9cce8b3fab5ac3ff67bb913ceeed587aed2a565708d5e4",
"Status": "Settled"
},
"EventType": "Transaction",
"EventVersion": 1764857544538,
"Occurred": "2025-12-04T14:12:24Z",
"UserID": "ory|5d8fcbdf-115d-4fbe-ae4a-82744c6417d1"
}

AdjustmentFor Field Reference

FieldDescription
AdjustedTransactionIDThe original deposit being refunded
AdjustmentIDMatches the RefundID in the Refunds array
ReasonWhy the adjustment was made (e.g., "Refund")

Bank OnRamp — Failed Deposit

When a fiat deposit fails compliance screening, the deposit is rejected and a refund is initiated.

Flow

#EventTypeStatusDescription
1FiatDepositPendingBank confirmation received
2FiatDepositFailedCompliance rejected; Refunds array populated

Example Payload

{
"Data": {
"ID": "96369c50-7fd3-4222-a76d-1c054e6ea9de",
"Status": "Failed",
"FiatAmount": "10.6",
"FiatCurrency": "EUR",
"Refunds": [
{
"RefundID": "1950886d-e2c2-444f-ac5c-eb8f94e9fc1b",
"RequestedTime": "2024-10-18T13:00:00Z",
"RefundedAmount": {
"Amount": "10.6",
"FiatCurrency": "EUR"
},
"Status": "Pending"
}
]
},
"EventType": "FiatDeposit"
}

Customer Onboarding

#EventTypeVerification.StatusDescription
1CustomerPendingForm submitted, KYC in progress
2CustomerApprovedKYC passed; customer can transact
2 (alt)CustomerDeclinedKYC failed; customer cannot transact

Understanding Direction + Network

DirectionNetworkWhat It Represents
InOffNetworkInternal ledger credit (fiat→crypto conversion)
InChain nameOn-chain crypto deposit received
OutOffNetworkFiat payout to bank
OutChain nameOn-chain crypto withdrawal/payout

All webhooks in a single orchestrated flow share the same Orchestration.RuleExecutionID. Use this to correlate related events.

"Orchestration": {
"RuleExecutionID": "36c54907-fadd-5a48-91f5-1632253f9a08",
"RuleID": "a23ed0ca-a205-5325-89b4-d2ac46e0b26b"
}

For Bank OnRamp flows, the PayIn transaction also links to the FiatDeposit via FiatPayment.FiatDepositID.


Key Questions Answered

QuestionAnswer
Which webhook = funds committed? (OffRamp)Transaction: Status: Settled, Direction: In
Which webhook = final settlement? (OffRamp)Transaction: Status: Settled, Direction: Out
Which webhook = final settlement? (OnRamp)Transaction: Status: Settled, Direction: Out, Network: <chain>
Why am I receiving multiple webhooks?Each webhook represents a status transition. 4-6 webhooks per flow is normal.
Why don't I see Pending in Sandbox?Relaxed risk rules cause fast Pending→Settled transition.
How do I correlate webhooks in a flow?Use Orchestration.RuleExecutionID
How do I link a refund to the original?Use AdjustmentFor.AdjustedTransactionID

Fields to Store for Reconciliation

FieldPurpose
Data.IDUnique identifier for this event
Data.PublicIDOn-chain tx hash (when available)
Data.ExternalIDYour external reference (set during rule creation via API)
Data.CustomerIDLink to your customer record
Orchestration.RuleExecutionIDCorrelate all events in a single flow
FiatPayment.FiatDepositIDLink Transaction back to FiatDeposit
AdjustmentFor.AdjustedTransactionIDLink refund to original transaction
EventVersionDeduplication and ordering
info

For Crypto OffRamp flows, you can set ExternalID when configuring the rule via the On-chain Deposit to Fiat Payout API. This is recommended for reconciliation. ExternalID may not appear on the initial crypto deposit webhooks.