Webhooks

Overview

Virtual account operations are asynchronous. Webhook events are sent to notify you of changes to account status, received funds, and sent funds. Configure your webhook endpoint to receive these notifications and keep your systems in sync.

Account Status Webhooks (VIBAN)

Since virtual account creation is asynchronous, webhook events are sent whenever an account's status changes. These events use the VIBAN prefix.

Event	Description
`VIBAN.PENDING`	Account has been requested and is awaiting provisioning
`VIBAN.ACTIVE`	Account has been provisioned and is ready to receive and send payments
`VIBAN.CLOSED`	Account has been closed
`VIBAN.FROZEN`	Account has been frozen

These events are sent for both primary wallet virtual accounts and custom wallet virtual accounts.

Example Webhook Event

{
  "accountId": "fa19be59-571d-4e9d-ac35-ddee805a5b22",
  "accountName": "Primary Account Number",
  "accountNumber": "1234567890",
  "apiKey": "19db5cdf8e61a8bf47d97cfa2b5ab82e",
  "bankAddress": "",
  "bankName": "Erebor Bank",
  "currency": "USD",
  "event": "VIBAN.PENDING",
  "executedAt": 1770368203203,
  "id": "fa19be59-571d-4e9d-ac35-ddee805a5b22",
  "routingNumber": "125108405",
  "status": "PENDING",
  "subwalletId": "54640e36-466a-5bb0-a47b-5044b28b416e",
  "swiftCode": "PCBBUS66XXX",
  "userId": "d7fbe40a-6d50-4607-8648-9827a54947c3"
}

{
  "accountId": "fa19be59-571d-4e9d-ac35-ddee805a5b22",
  "accountName": "Primary Account Number",
  "accountNumber": "1234567890",
  "apiKey": "19db5cdf8e61a8bf47d97cfa2b5ab82e",
  "bankAddress": "",
  "bankName": "Erebor Bank",
  "currency": "USD",
  "event": "VIBAN.ACTIVE",
  "executedAt": 1770368203203,
  "id": "fa19be59-571d-4e9d-ac35-ddee805a5b22",
  "routingNumber": "125108405",
  "status": "PENDING",
  "subwalletId": "54640e36-466a-5bb0-a47b-5044b28b416e",
  "swiftCode": "PCBBUS66XXX",
  "userId": "d7fbe40a-6d50-4607-8648-9827a54947c3"
}

Field	Description
`accountId`	Virtual account unique identifier
`accountName`	Account holder name
`accountNumber`	Bank account number
`apiKey`	The API key used to sign this webhook (see Verifying Webhook Signatures)
`bankName`	Bank name
`currency`	Account currency code
`event`	The webhook event type (e.g., `VIBAN.PENDING`)
`executedAt`	Unix timestamp (ms) when the event occurred
`id`	Event identifier
`routingNumber`	Bank routing number (if applicable)
`status`	Current account status
`subwalletId`	Associated custom wallet ID (if applicable)
`swiftCode`	SWIFT code (if applicable)
`userId`	Partner identifier who owns the account

Receive Webhooks

Webhook events are sent when funds are received into your virtual accounts. All deposits are processed as receives, and receive webhook events are fired for both primary and custom wallet virtual accounts.

Send Webhooks

When you send funds from a virtual account using the Payments API, payment webhook events are sent to notify you of the payment status.

Payment Webhook Events

For detailed information on receive and send webhook event types and statuses, refer to the Webhooks and Events pages.

Verifying Webhook Signatures

Every webhook is signed, so you can verify it genuinely came from Yellow Card. Verify the signature on every webhook before acting on it. Visit the Webhook guide page to learn more about webhooks.

Which key signs your webhooks

Webhooks are signed with one of your partner API keys' secret. When a webhook is triggered by an internal Yellow Card process rather than a direct API call from you — which is the case for all virtual accounts (VIBAN) events and for receives into a virtual account — there is no request-scoped API key to sign with. In that case, Yellow Card selects a signing key from your account using the following hierarchy:

The oldest active API key with api_write permission.
If you have no active api_write key, the oldest active API key of any permission.

The selected key is always an active key; disabled or expired keys are never used. Because the oldest active api_write key is preferred and this choice is stable over time, you can verify webhook signatures against the secret of that key.

Each webhook payload also includes an apiKey field containing the API key that was used to sign that request. Use it to look up the corresponding secret key and verify the signature.

Recommendation: Keep a single long-lived active api_write key as your designated webhook-signing key, and verify all virtual-account and receive webhooks against that key's secret.