> ## 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.

# Webhooks for Virtual Accounts

Subscribe to these events to react to virtual-account activity in real time.
Full payload schemas are in [WebHook Events](/api-reference/webhook-events).

## Account activities

| Event                                     | Fires when                                                                  |
| ----------------------------------------- | --------------------------------------------------------------------------- |
| `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 virtual account number is generated for the main account or a sub-account |

## Transaction activities

| Event family                                    | Fires when                                                                                    |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `transaction_activity.account_number_deposit.*` | A deposit lands on a virtual account number (`.created`, `.updated`, `.completed`, `.failed`) |
| `transaction_activity.internal_transfer.*`      | A transfer completes between your main account and a sub-account, or between two sub-accounts |

### Sample payloads

Full field-by-field schemas for every event are in
[WebHook Events](/api-reference/webhook-events#account-activity-samples).

<AccordionGroup>
  <Accordion title="account_activity.sub_account.created">
    ```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
    }
    ```
  </Accordion>

  <Accordion title="transaction_activity.account_number_deposit.completed">
    ```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,
          "currency": "NGN",
          "accountCurrency": "USD",
          "status": "SUCCESS",
          "settlementAmount": 100.00,
          "createdDate": "2026-07-20T08:15:00.000Z"
        }
      },
      "timestamp": 1784535405
    }
    ```
  </Accordion>

  <Accordion title="transaction_activity.internal_transfer.completed">
    ```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",
        "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",
          "createdDate": "2026-07-21T18:04:22.000Z"
        }
      },
      "timestamp": 1784657110
    }
    ```
  </Accordion>
</AccordionGroup>