Documentation Index Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
Use this file to discover all available pages before exploring further.
Yativo Crypto fires webhook events for every significant state change across wallets, transactions, cards, IBAN accounts, and system events. Configure webhooks once and your server stays in sync without polling.
For webhook management (creating, updating, deleting webhook endpoints), see the Webhook Management docs. This page covers the crypto-specific event types and their payloads.
interface Webhook { webhook_id : string ; url : string ; events : WebhookEventType []; description ?: string ; status : "active" | "inactive" ; created_at : string ; } type WebhookEventType = | "deposit.detected" | "deposit.confirmed" | "withdrawal.initiated" | "withdrawal.completed" | "withdrawal.failed" | "transaction.completed" | "transaction.failed" | "swap.completed" | "swap.failed" | "card.funded" | "card.transaction.completed" | "card.transaction.failed" | "iban.activated" | "iban.transfer.received" | "gas.low" ; interface CreateWebhookRequest { url : string ; events : WebhookEventType []; description ?: string ; }
Crypto Event Types Deposit Events Event Fired When deposit.detectedAn inbound transaction is detected on-chain (unconfirmed) deposit.confirmedAn inbound transaction has reached sufficient block confirmations
Withdrawal Events Event Fired When withdrawal.initiatedA withdrawal transaction has been broadcast to the network withdrawal.completedA withdrawal has been confirmed on-chain withdrawal.failedA withdrawal failed (insufficient funds, network error, etc.)
Transaction Events Event Fired When transaction.completedAny transaction (deposit or withdrawal) has been fully confirmed transaction.failedA transaction failed for any reason
Swap Events Event Fired When swap.completedA token swap has settled and destination tokens have been delivered swap.failedA swap failed; source funds have been returned
Card Events Event Fired When card.fundedA card’s balance has been topped up card.transaction.completedA card payment has been approved and settled card.transaction.failedA card payment was declined or failed
IBAN Events Event Fired When iban.activatedAn IBAN account has been activated and is ready to receive funds iban.transfer.receivedA SEPA transfer has been received into the IBAN account
System Events Event Fired When autoforward.completedAn auto-forward rule has executed and funds have been moved gas.lowA gas station’s balance has dropped below the configured threshold
Webhook Payload Examples All payloads share the same envelope structure:
{ "id" : "evt_01abc123" , "type" : "<event_type>" , "created_at" : "2026-03-26T10:05:00Z" , "data" : { ... } }
deposit.confirmed { "id" : "evt_01abc123" , "type" : "deposit.confirmed" , "created_at" : "2026-03-26T10:05:00Z" , "data" : { "asset_id" : "asset_01xyz789" , "account_id" : "acc_01abc123" , "chain" : "solana" , "ticker" : "USDC_SOL" , "amount" : "250.00" , "from_address" : "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" , "to_address" : "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" , "tx_hash" : "5KtP3jNHGXi8YmD2L9sRZVAoWqFcBe4TrKlUvJpMxNy" , "confirmations" : 1 , "new_balance" : "750.00" } }
withdrawal.completed { "id" : "evt_02def456" , "type" : "withdrawal.completed" , "created_at" : "2026-03-26T10:07:30Z" , "data" : { "transaction_id" : "txn_01pqr456" , "asset_id" : "asset_01xyz789" , "chain" : "ethereum" , "ticker" : "USDC" , "amount" : "100.00" , "to_address" : "0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4" , "tx_hash" : "0xabc123def456789..." , "fee_usd" : "3.18" , "new_balance" : "400.00" } }
transaction.failed { "id" : "evt_03ghi789" , "type" : "transaction.failed" , "created_at" : "2026-03-26T10:10:00Z" , "data" : { "transaction_id" : "txn_02stu789" , "chain" : "ethereum" , "ticker" : "USDC" , "amount" : "1000.00" , "error_code" : "insufficient_balance" , "error_message" : "Wallet balance (400.00 USDC) is less than requested amount (1000.00 USDC)" } }
swap.completed { "id" : "evt_04jkl012" , "type" : "swap.completed" , "created_at" : "2026-03-26T10:08:20Z" , "data" : { "swap_id" : "swap_01def456" , "from_chain" : "ethereum" , "from_ticker" : "USDC" , "from_amount" : "500.00" , "to_chain" : "solana" , "to_ticker" : "USDC_SOL" , "to_amount" : "498.71" , "to_address" : "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" , "source_tx_hash" : "0xabc123..." , "destination_tx_hash" : "5KtP3jNHGXi..." } }
card.transaction.completed { "id" : "evt_05mno345" , "type" : "card.transaction.completed" , "created_at" : "2026-03-26T11:00:00Z" , "data" : { "card_id" : "card_01abc" , "transaction_id" : "card_txn_01xyz" , "merchant_name" : "Amazon" , "merchant_category" : "Shopping" , "amount" : "49.99" , "currency" : "USD" , "status" : "approved" , "new_balance" : "450.01" } }
iban.transfer.received { "id" : "evt_06pqr678" , "type" : "iban.transfer.received" , "created_at" : "2026-03-26T12:00:00Z" , "data" : { "iban_id" : "iban_01abc" , "iban_number" : "DE89370400440532013000" , "amount" : "1000.00" , "currency" : "EUR" , "sender_name" : "John Smith" , "sender_iban" : "GB29NWBK60161331926819" , "reference" : "Invoice #INV-2026-042" , "received_at" : "2026-03-26T12:00:00Z" } }
gas.low { "id" : "evt_07stu901" , "type" : "gas.low" , "created_at" : "2026-03-26T11:00:00Z" , "data" : { "station_id" : "station_01abc123" , "chain" : "ethereum" , "ticker" : "ETH" , "balance" : "0.08" , "balance_usd" : "200.00" , "threshold" : "0.10" } }
Signature Verification Every webhook request includes an X-Webhook-Signature header. Always verify it before processing:
import crypto from 'crypto' ; function verifySignature ( rawBody : Buffer , signature : string , secret : string ) : boolean { const expected = crypto . createHmac ( 'sha256' , secret ). update ( rawBody ). digest ( 'hex' ); return crypto . timingSafeEqual ( Buffer . from ( signature , 'hex' ), Buffer . from ( expected , 'hex' )); }
See the Webhook Management page for verification examples in Python and PHP.
Setting Up Webhooks Use the webhook management API to register your endpoint:
curl -X POST https://crypto-api.yativo.com/api/v1/webhook/create \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhooks/yativo-crypto", "events": [ "deposit.confirmed", "withdrawal.completed", "withdrawal.failed", "swap.completed", "card.transaction.completed", "gas.low" ], "description": "Yativo Crypto production webhook" }'
For full webhook management documentation (list, update, delete, retry), see Webhook Management . 
