Webhooks for Accounts
Get a signed event on your server when money arrives, a transaction is booked or a statement is ready, covering the six Accounts events, which endpoints get them, the event object, checking the Standard Webhooks signature, replies and retries, test events, resending and catching up on missed events.
Overview
Accounts events tell your server what happened on your accounts: money is arriving, it reached your balance, a line
was booked, a month's statement is ready. Each one is a signed JSON POST to an endpoint you add in the dashboard, in
the Standard Webhooks format. We queue each delivery and try again for about 3 days
if your server doesn't answer, and statement.available comes within about 6 hours of a month closing.
They need the Accounts API on for your business. See Get access to the Accounts API.
The events
| Event | When it is sent |
|---|---|
incoming.received | Money is arriving in one of your accounts. It is not in your balance yet. |
incoming.held | We are reviewing money that arrived before it reaches your balance. |
incoming.credited | Money that arrived is now in your balance. |
incoming.returned | Money that was arriving failed or was sent back before it reached your balance. |
transaction.posted | A line was booked on one of your balances: money in, a transfer, a fee or a correction. One event per line, the stream to keep your books in step. |
statement.available | A month closed and its statement for an account is ready. |
Events can arrive in another order, or twice. Use each event's id to skip one you already handled.
Moving money between your own balances isn't money arriving: it sends no incoming events, only transaction.posted
for each line. statement.available is never sent for a month that closed before the Accounts API was on for your
business.
Which endpoints get them
Accounts events go only to endpoints that:
- use the Standard Webhooks signing format, and
- are set to Test or Live. Test endpoints get sandbox events, live endpoints get real ones.
An endpoint in the current Vezmo format can't listen to them: add a new endpoint for them. A business can have up to 16 endpoints per environment.
Add an endpoint
In Developers, open Webhooks and select Add endpoint. Enter the https URL and choose Test or Live.
Choose Standard Webhooks
Under How we sign events, choose Standard Webhooks. The Accounts events section stays locked until you do; Use Standard Webhooks in that section switches it for you.
Tick the Accounts events
Under Accounts events, tick each one you want. An endpoint gets only the events ticked.
Confirm and save the secret
Select Create Webhook and type the code we email you. The signing secret is shown once: keep it on your server.
The event
Every event has the same shape, in the webhook body and in the events list:
- id
- The event id (
evt_…). It is also thewebhook-idheader. - type
- The event, like
incoming.credited. - apiVersion
- The API version the event is written in.
- createdAt
- When it happened, in UTC.
- livemode
falsefor sandbox events,truefor real ones.- data.object
- A small snapshot of what changed: the arrival, the transaction or the statement. Account numbers are masked.
- data.previousStatus
- What its status was before this change, or null.
The full payloads are in the Accounts API reference.
Check the signature
Each delivery carries three headers:
webhook-id: the event id;webhook-timestamp: when it was sent, in Unix seconds;webhook-signature:v1,and the signature, an HMAC-SHA256 of the id, the timestamp and the body, made with your endpoint's signing secret. While a rolled secret is still in its overlap, it carries two signatures.
Check every delivery with a Standard Webhooks library, which does all of this for you. Refuse a delivery whose signature doesn't match, or whose timestamp is more than 5 minutes old. Code for Node, Python, PHP and more is in the webhook verification guide.
Replies and retries
- Answer with any
2xxwithin 15 seconds. Do the slow work after you reply. - Anything else is tried again up to 10 times over about 3 days: at once, then after 5 seconds, 5 minutes, 30 minutes,
2, 5, 10, 14, 20 and 24 hours. A
Retry-Afterheader on a429or503is respected. - A test endpoint gets 5 seconds per attempt and 3 attempts in all (at once, after 5 seconds and after 5 minutes), so a sandbox server that is down doesn't wait days. A test event sent to a live endpoint is tried the same way.
- An endpoint that answers
410 Goneis switched off at once, and we email you. - An endpoint that fails 50 times in a row over 3 days or more is switched off too, and we email you.
Test events, resending and missed events
- Send a test event. On an endpoint's row, select the send icon (Send a test event). A signed
webhook.testevent goes to that endpoint once, and shows in its deliveries. - Send again. In an endpoint's deliveries, Send again sends the same event once more, with the same id, up to 30 days back. Accounts deliveries and test events stay in the delivery log for 30 days.
- Send an Accounts event again. On an endpoint's row, give an event id from the last 30 days: it goes to that endpoint once, even if it never got it.
- Catch up. Events stay in the events list for 30 days. After an outage, read them with
GET /events(theevents.readpermission), starting 5 minutes before the newest event you already have, and skip the ids you already have. An event can arrive twice, so always check its id.
Roll the signing secret
On the endpoint's row, select Roll the signing secret and choose how long the old secret keeps signing: none, 1 hour, 24 hours or 7 days. During the overlap each event carries both signatures, so your server can move to the new secret when it is ready. See Webhooks.
Related
Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated partners.
Facts checked against the product on 14 Nov 2026.
Was this page helpful?
Statements by API
Read your monthly account statements with the Accounts API, covering one statement per account per month, when a month is final, JSON, CSV and PDF, large months in parts, what the CSV columns hold, masked account details, limits and the statement.available event.
Sandbox for the Accounts API
Build and test against simulated accounts with a test key, covering opening a test account, making money arrive, holding and returning an arrival, the events it sends, what works like live, and the sandbox's limits.