Skip to main content
This guide sets up your server to receive the webhook events of virtual accounts and to act on each one. Crossmint sends two kinds of events. One event reports a change in the status of an account. The order events report each step of a deposit, because every bank transfer into an account is an order.

Prerequisites

  • Account: a virtual account, opened as in Open a Virtual Account.
  • Webhook endpoint: a public HTTPS endpoint on your server that verifies the signature of each delivery, as described in Webhooks.
  • API Key: a server API key with the virtual-accounts.read and orders.read scopes, to read the account or the order after each event. In staging, all scopes are included by default.

Subscribe to the Events

In the Crossmint Console, add your endpoint and subscribe it to the events below, as described in Webhooks. Every delivery is signed, and a failed delivery is retried.

Handle Account Status Changes

virtual_accounts.status.updated fires each time the status of an account changes, and when the statusReason changes while the status stays. See Account Statuses for every value.
virtual_accounts.status.updated
The event carries no bank details, wallet, or label. When it arrives, read the account with GET /api/2026-09-16/virtual-accounts/{virtualAccountId}, and show the bank details as a way to add funds only when status is active. No event fires for the create response, for a repeated create, or for a DELETE that changes nothing. An account that is active in the create response sends no event.

Handle Deposit Events

Every order event is delivered as actionId, type, and data. data is the full order, identical to the Get Order response, including the deposit fields payment.payer.virtualAccountId, payment.reference, and payment.sender.
orders.payment.succeeded
The events of a deposit arrive in a set order for each outcome. Every deposit starts with orders.quote.created. When an order event arrives, update the deposit in your app from the order. See Deposit States for the fields of the order at each step.

Make Your Handler Reliable

  • Return a 2xx status quickly. Your server must answer with a 2xx HTTP status so the webhook is marked as delivered. Do the work after you answer.
  • Deduplicate. A retried delivery carries the same svix-id header. Process each svix-id once.
  • Read after every event. When an event arrives, read the account or the order from the API and use that response, not the event payload, as the current state.
  • Expect events out of order. For account events, use sequence so older data never overwrites newer state.
  • Do not treat acceptance as final. orders.payment.succeeded means Crossmint accepted the deposit. A deposit can still go back before it is delivered. After delivery, nothing goes back.
  • Expect repeats of return events. A second orders.payment.refund_sent can arrive for the same order, when an earlier return did not go through.
  • Accept new fields. Do not validate payloads strictly. Crossmint can add fields and values to these events.

Next Steps

Track Deposits

The states and fields of each deposit

Test in Staging

Simulate deposits and receive every event