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

Source: https://vezmo.com/docs/developers/accounts-api-webhooks


## 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](https://www.standardwebhooks.com) 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](/docs/developers/accounts-api-access).

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

(Diagram: Money arriving sends incoming.received. If we review it, incoming.held follows. When it reaches the balance, incoming.credited is sent together with transaction.posted for the booked line.)

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.

1. **Add an endpoint**
In **Developers**, open **Webhooks** and select **Add endpoint**. Enter the https URL and choose **Test** or **Live**.

2. **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.

3. **Tick the Accounts events**
Under **Accounts events**, tick each one you want. An endpoint gets only the events ticked.

4. **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 the `webhook-id` header.
- **type**:The event, like `incoming.credited`.
- **apiVersion**:The API version the event is written in.
- **createdAt**:When it happened, in UTC.
- **livemode**:`false` for sandbox events, `true` for 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.

**Read the current state before you act on money:**
An event is a notice, not the record. Before you ship an order or close an invoice, read the transaction or the
statement through the API, which gives its current state.

The full payloads are in the [Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api/events).

## 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](https://user.vezmo.com/docs/v1/accounts-api/events#verify-a-webhook).

## Replies and retries

- Answer with any `2xx` within 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-After` header on a `429` or `503` is 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 Gone` is 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.test`
  event 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` (the
  `events.read` permission), 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](/docs/developers/webhooks).

## Related

- [Webhooks](/docs/developers/webhooks)
- [Accounts API](/docs/developers/accounts-api)
- [Events in the Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api/events)

Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated
partners.
