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.
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:
| Status | Meaning |
|---|---|
| Pending | Processing in progress |
| Settled | Successfully completed |
| Failed | Did not complete; check for refund information |
Transitions: Pending → Settled OR Pending → Failed
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
| # | EventType | Status | Direction | Network | Meaning |
|---|---|---|---|---|---|
| 1 | FiatDeposit | Pending | — | — | Bank confirmation received |
| 2 | FiatDeposit | Settled | — | — | Risk/KYT approved |
| 3 | Transaction | Pending | In | OffNetwork | Fiat converted to stablecoin |
| 4 | Transaction | Pending | Out | Chain name | On-chain payout initiated |
| 5 | Transaction | Settled | In | OffNetwork | Internal ledger credit confirmed |
| 6 | Transaction | Settled | Out | Chain name | On-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
| # | EventType | Status | Direction | Network | Meaning |
|---|---|---|---|---|---|
| 1 | Transaction | Pending | In | Chain name | Crypto deposit received |
| 2 | Transaction | Settled | In | Chain name | Risk passed, deposit confirmed |
| 3 | Transaction | Pending | Out | OffNetwork | Fiat payout initiated |
| 4 | Transaction | Settled | Out | OffNetwork | Bank 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
| # | EventType | Status | Direction | Description |
|---|---|---|---|---|
| 1 | Transaction | Pending | In | Crypto deposit received |
| 2 | Transaction | Settled | In | Crypto deposit confirmed |
| 3 | Transaction | Pending | Out | Fiat payout initiated |
| 4 | Transaction | Failed | Out | Fiat payout failed |
| 5 | Transaction | Settled | In | Original deposit updated with Refunds array |
| 6 | Transaction | Settled | Out | Refund 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
| Field | Description |
|---|---|
AdjustedTransactionID | The original deposit being refunded |
AdjustmentID | Matches the RefundID in the Refunds array |
Reason | Why 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
| # | EventType | Status | Description |
|---|---|---|---|
| 1 | FiatDeposit | Pending | Bank confirmation received |
| 2 | FiatDeposit | Failed | Compliance 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
| # | EventType | Verification.Status | Description |
|---|---|---|---|
| 1 | Customer | Pending | Form submitted, KYC in progress |
| 2 | Customer | Approved | KYC passed; customer can transact |
| 2 (alt) | Customer | Declined | KYC failed; customer cannot transact |
Understanding Direction + Network
| Direction | Network | What It Represents |
|---|---|---|
| In | OffNetwork | Internal ledger credit (fiat→crypto conversion) |
| In | Chain name | On-chain crypto deposit received |
| Out | OffNetwork | Fiat payout to bank |
| Out | Chain name | On-chain crypto withdrawal/payout |
Linking Related Webhooks
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
| Question | Answer |
|---|---|
| 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
| Field | Purpose |
|---|---|
Data.ID | Unique identifier for this event |
Data.PublicID | On-chain tx hash (when available) |
Data.ExternalID | Your external reference (set during rule creation via API) |
Data.CustomerID | Link to your customer record |
Orchestration.RuleExecutionID | Correlate all events in a single flow |
FiatPayment.FiatDepositID | Link Transaction back to FiatDeposit |
AdjustmentFor.AdjustedTransactionID | Link refund to original transaction |
EventVersion | Deduplication and ordering |
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.