> ## Documentation Index > Fetch the complete documentation index at: https://docs.onboard.xyz/llms.txt > Use this file to discover all available pages before exploring further. # WebHook Events This is the complete catalogue of webhook events Onboard Business can deliver to your registered webhook URL. Each product guide links back to the subset relevant to it; this page is the authoritative reference for all of them. Every delivery uses the envelope described in [Webhook Verification](/api-reference/webhook-verification): ```json theme={null} { "event": "", "data": { /* event-specific payload */ }, "timestamp": 1732718962 } ``` ## Account activity events Fired when something changes about an account, sub-account, or a saved beneficiary/offramp account — not a movement of money. | Event | Trigger | | --------------------------------------------- | ------------------------------------------------------------------------ | | `account_activity.sub_account.created` | A sub-account is created | | `account_activity.sub_account.updated` | A sub-account's name or frozen status changes | | `account_activity.sub_account.deleted` | A zero-balance sub-account is deleted | | `account_activity.account_number.created` | A cash-deposit virtual account number is generated (main or sub-account) | | `account_activity.fiat_beneficiary.created` | A fiat beneficiary (bank account) is added | | `account_activity.fiat_beneficiary.deleted` | A fiat beneficiary is deleted | | `account_activity.crypto_beneficiary.created` | A crypto beneficiary (wallet + network) is added | | `account_activity.crypto_beneficiary.deleted` | A crypto beneficiary is deleted | | `account_activity.offramp_account.created` | An offramp account is created | | `account_activity.offramp_account.deleted` | An offramp account is deleted | ## Transaction activity events Fired for money movement. Each activity type emits **four** lifecycle events: `.created`, `.updated`, `.completed`, `.failed`. | Event prefix | Activity | | ----------------------------------------------- | ----------------------------------------------------------------------------------- | | `transaction_activity.cash_deposit.*` | Cash deposit | | `transaction_activity.cash_payment.*` | Cash payment (payout) | | `transaction_activity.crypto_withdrawal.*` | Crypto withdrawal | | `transaction_activity.crypto_deposit.*` | Crypto deposit | | `transaction_activity.offramp_deposit.*` | Offramp deposit | | `transaction_activity.internal_transfer.*` | Internal transfer (between main account and a sub-account, or between sub-accounts) | | `transaction_activity.account_number_deposit.*` | Account-number deposit | Lifecycle suffixes: * **`.created`** — the activity was created. `data.status` is typically `PENDING`. * **`.updated`** — a non-terminal status change. `data.status` is typically `IN_PROGRESS`. * **`.completed`** — reached a terminal success state. `data.status` is `SUCCESS`. * **`.failed`** — reached a terminal failure state. `data.status` is `FAILED`. The event name's suffix (`.completed`, `.failed`, ...) describes the lifecycle transition that triggered delivery. The payload's own `status` field is always one of the four `TransactionStatus` values above — there is no `COMPLETED` status value; the terminal success state is `SUCCESS`. A single underlying transaction can emit more than one event of the same name — for example, one for a sub-account's activity row and one for its parent main-account row. Treat deliveries as at-least-once and deduplicate on the payload's activity id, not on event name plus timestamp. ## Sample payloads Every sample below is constructed directly from the corresponding schema object in the [OpenAPI spec](/api-reference/openapi.yml) — the same shape you'd get back from the matching REST endpoint. ### Account activity samples All three sub-account lifecycle events share the `SubAccount` shape. `.updated` and `.deleted` deliveries reflect the sub-account's state at the time of the change (e.g. `frozen: true` for a freeze, or the balance at deletion). ```json theme={null} { "event": "account_activity.sub_account.created", "data": { "id": "6f9d3a2e-1b5c-4e88-9a2f-3c7d5e9b1a04", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "reference": "customer-8841", "displayName": "Customer 8841", "currency": "USD", "accountBalance": { "balance": 0, "availableBalance": 0 }, "frozen": false, "createdDate": "2026-07-19T15:30:00.000Z" }, "timestamp": 1784475000 } ``` The destination account details generated for a cash deposit virtual account number. The event fires on whichever account or sub-account requested the account number; the request itself (not the payload) tells you which. ```json theme={null} { "event": "account_activity.account_number.created", "data": { "details": { "accountInfoType": "CashLocalBankAccount", "accountName": "Onboard Business Ltd", "accountNumber": "0123456789", "bankName": "Providus Bank", "bankCode": "101", "reference": "PROV123456" }, "payinCurrency": "NGN" }, "timestamp": 1784535300 } ``` ```json theme={null} { "event": "account_activity.fiat_beneficiary.created", "data": { "id": "5a83377d-7c57-4725-992f-9c50349af917", "accountNumber": "0123456789", "accountName": "Jane Doe", "currency": "GHS", "beneficiaryType": "BeneficiaryLocalBankAccount", "bankName": "GCB Bank", "bankCode": "040", "isThirdParty": false, "accountHolderType": "INDIVIDUAL" }, "timestamp": 1784657062 } ``` ```json theme={null} { "event": "account_activity.crypto_beneficiary.created", "data": { "id": "e2a1c4b8-3d5f-4a2e-9b1c-7f8e6d5c4b3a", "address": "0x7BCc5bCBa19DE3C903F062D8fB5fF8d9f818173E", "network": "BASE", "name": "Treasury wallet", "memo": null }, "timestamp": 1784711523 } ``` ```json theme={null} { "event": "account_activity.offramp_account.created", "data": { "id": "60037f44-9094-4bd5-a316-21995e8985c9", "beneficiary": { "id": "5a83377d-7c57-4725-992f-9c50349af917", "accountNumber": "1234567890123", "accountName": "Jane Doe", "currency": "KES", "beneficiaryType": "BeneficiaryMobileWalletAccount", "isThirdParty": false, "accountHolderType": "INDIVIDUAL" }, "payoutCurrency": "KES", "status": "ACTIVE", "createdDate": "2026-07-23T11:22:00.000Z" }, "timestamp": 1784805720 } ``` ### Transaction activity samples Every `transaction_activity.*` payload is a `TransactionActivity` — a common envelope (`id`, `type`, `direction`, `amount`, `currency`, `status`, `accountId`, `accountType`, `activityAt`, ...) plus an `activityData` object whose shape depends on `activityType`, per the discriminator on the `TransactionActivity` schema. ```json theme={null} { "event": "transaction_activity.cash_deposit.completed", "data": { "id": "1b3e6c2a-9f41-4b8e-8a2d-5c7f9e1a3b04", "activityType": "CashDepositActivity", "type": "CASH_DEPOSIT", "direction": "CREDIT", "amount": 32.50, "currency": "USD", "status": "SUCCESS", "reference": "0173270620673048624933", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "SUB_ACCOUNT", "subAccountId": "6f9d3a2e-1b5c-4e88-9a2f-3c7d5e9b1a04", "activityAt": "2026-07-22T13:59:12.140Z", "activityData": { "id": "3c7f9e1a-3b04-4e88-9a2f-1b3e6c2a5c7d", "reference": "0173270620673048624933", "currency": "USD", "status": "SUCCESS", "payinCurrency": "NGN", "amount": 32.50, "rate": 1538.46, "payinAmount": 50000.00, "createdDate": "2026-07-22T13:57:56.970Z" } }, "timestamp": 1784728752 } ``` ```json theme={null} { "event": "transaction_activity.cash_payment.completed", "data": { "id": "9c4b1a2e-7d5f-4a2e-9b1c-3d5f8e6d5c4b", "activityType": "CashPaymentActivity", "type": "CASH_PAYMENT", "direction": "DEBIT", "amount": 1200.00, "currency": "USD", "status": "SUCCESS", "reference": "0173270620673048624933", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "MAIN", "activityAt": "2026-07-23T11:24:37.000Z", "activityData": { "id": "5c4b3a2e-9c4b-4a2e-9b1c-7d5f8e6d1a2e", "reference": "0173270620673048624933", "currency": "USD", "status": "SUCCESS", "payoutCurrency": "GHS", "amount": 1200.00, "rate": 15.20, "payoutAmount": 18240.00, "recipient": { "id": "5a83377d-7c57-4725-992f-9c50349af917", "accountName": "Jane Doe", "beneficiaryType": "BeneficiaryLocalBankAccount", "bankName": "GCB Bank", "accountIdentifier": "0123456789", "paymentChannelId": "BANK_TRANSFER_GHANA" }, "createdDate": "2026-07-23T11:22:00.000Z" } }, "timestamp": 1784805877 } ``` ```json theme={null} { "event": "transaction_activity.account_number_deposit.completed", "data": { "id": "2e1a4c8b-5d3f-4a2e-9b1c-8e6d5c4b3a7f", "activityType": "AccountNumberDepositActivity", "type": "ACCOUNT_NUMBER_DEPOSIT", "direction": "CREDIT", "amount": 100.00, "currency": "USD", "status": "SUCCESS", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "MAIN", "activityAt": "2026-07-20T08:16:45.000Z", "activityData": { "id": "4a2e9b1c-7f8e-4d5c-8b3a-2e1a4c8b5d3f", "amount": 145000.00, "fee": 500.00, "currency": "NGN", "accountCurrency": "USD", "status": "SUCCESS", "settlementAmount": 100.00, "settlementExchangeRate": 1450.00, "createdDate": "2026-07-20T08:15:00.000Z" } }, "timestamp": 1784535405 } ``` Both crypto event families share the `AccountTransaction` shape for `activityData`; only `direction` and `activityType` differ. ```json theme={null} { "event": "transaction_activity.crypto_withdrawal.completed", "data": { "id": "8e6d5c4b-3a7f-4a2e-9b1c-2e1a4c8b5d3f", "activityType": "CryptoWithdrawalActivity", "type": "CRYPTO_WITHDRAWAL", "direction": "DEBIT", "amount": 150.00, "currency": "USD", "status": "SUCCESS", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "SUB_ACCOUNT", "subAccountId": "6f9d3a2e-1b5c-4e88-9a2f-3c7d5e9b1a04", "activityAt": "2026-07-24T10:00:05.000Z", "activityData": { "id": "txn_9f41b3e6c2a", "reference": "REF9F41B3E6C2A", "type": "WITHDRAWAL", "amount": -150.00, "currency": "USD", "status": "SUCCESS", "categoryTag": "crypto-withdrawal", "notes": "Withdrawal to USDC on BASE", "createdDate": "2026-07-24T10:00:00.000Z" } }, "timestamp": 1784887205 } ``` ```json theme={null} { "event": "transaction_activity.internal_transfer.completed", "data": { "id": "3d5f8e6d-5c4b-4a2e-9b1c-9c4b1a2e7d5f", "activityType": "InternalTransferActivity", "type": "INTERNAL_TRANSFER", "direction": "DEBIT", "amount": 500.00, "currency": "USD", "status": "SUCCESS", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "MAIN", "groupId": "7c9f1a3b-04e8-4a2e-9b1c-1b3e6c2a9f41", "activityAt": "2026-07-21T18:05:10.000Z", "activityData": { "reference": "ITR9F41B3E6C2A", "sourceAccountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "destinationAccountId": "6f9d3a2e-1b5c-4e88-9a2f-3c7d5e9b1a04", "amount": 500.00, "currency": "USD", "status": "SUCCESS", "description": "Rebalance to Customer 8841", "createdDate": "2026-07-21T18:04:22.000Z" } }, "timestamp": 1784657110 } ``` `activityData` extends `CashPaymentTransaction` with `offrampAccountId` and `blockchainInfo`. ```json theme={null} { "event": "transaction_activity.offramp_deposit.completed", "data": { "id": "4a2e9b1c-8e6d-4a2e-9b1c-3d5f8e6d5c4b", "activityType": "OfframpDepositActivity", "type": "OFFRAMP_DEPOSIT", "direction": "CREDIT", "amount": 500.00, "currency": "USD", "status": "SUCCESS", "accountId": "d9e9f9c1-6a3b-4b2e-8b3a-2f1e4d5c6b7a", "accountType": "OFFRAMP_ACCOUNT", "activityAt": "2026-07-23T11:24:37.000Z", "activityData": { "id": "5c4b3a2e-8e6d-4a2e-9b1c-7d5f8e6d1a2e", "reference": "0173270620673048624933", "currency": "USD", "status": "SUCCESS", "payoutCurrency": "NGN", "amount": 500.00, "rate": 1450.00, "payoutAmount": 725000.00, "recipient": { "id": "5a83377d-7c57-4725-992f-9c50349af917", "accountName": "Jane Doe", "beneficiaryType": "BeneficiaryMobileWalletAccount", "accountIdentifier": "2348012345678", "paymentChannelId": "MOBILE_MONEY_NIGERIA" }, "offrampAccountId": "60037f44-9094-4bd5-a316-21995e8985c9", "createdDate": "2026-07-23T11:22:00.000Z" } }, "timestamp": 1784805877 } ```