Vezmo App

Accounts API · Accounts API

Events and webhooks

What happened on your accounts. Read events with GET /events (events.read), or receive them as signed webhooks in the Standard Webhooks format. Only businesses with the Accounts API on get events, and never VezmoPay's payment events here.

Event types

  • incoming.received — money is arriving; not in your balance yet. Once per arrival.
  • incoming.held — we are reviewing it before it reaches your balance.
  • incoming.credited — it reached your balance.
  • incoming.returned — it failed or was sent back before it reached your balance.
  • transaction.posted — a line was booked on a balance; one per line. The stream for ERPs.
  • statement.available — a month closed and an account's statement for it is final (sent within about 6 hours of the month closing; a missed month is caught up later). Never for a month that closed before the business's access was switched on.

A move between the business's own balances is not money in: it fires no incoming.*; its lines still come as transaction.posted with incomingId: null.

The event object

The same in GET /events and in a webhook body. data.object is a small masked snapshot (an incoming, a transaction or a statement); fetch the current state before acting on money. livemode is false for sandbox events. Ordering isn't guaranteed: dedupe on id.

incoming.credited
{
  "id": "evt_cm3k9r8te0007",
  "object": "event",
  "type": "incoming.credited",
  "apiVersion": "2026-11-14",
  "createdAt": "2026-11-14T10:00:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "inc_cm3k9q0aa0002",
      "object": "incoming",
      "accountId": "acct_cm2v8q1k70003",
      "status": "credited",
      "amount": 125000,
      "currency": "USD",
      "fee": 100,
      "credited": 124900,
      "payerName": "Harbor & Co.",
      "payerCountry": "US",
      "rail": "ach",
      "coin": null,
      "network": null,
      "createdAt": "2026-11-14T09:41:00.000Z",
      "creditedAt": "2026-11-14T10:00:00.000Z"
    },
    "previousStatus": "pending"
  }
}

List events — GET /events

  • type — one type, or a group like incoming.*.
  • objectId — inc_…, txn_… or stmt_….
  • createdFrom, createdTo — RFC 3339 with a zone. Events older than 30 days aren't listed; an older createdFrom is read as 30 days ago.
  • limit, startingAfter. Newest first.
Request
curl "https://api.vezmo.com/api/v1/events?type=incoming.*&createdFrom=2026-11-13T00:00:00Z" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Reading the list to stay in step: ask from the newest createdAt you have minus 5 minutes (createdFrom), and skip ids you already have. Events can arrive twice; dedupe on id.

GET /events/{id} returns one; another business's, another mode's or one older than 30 days answers 404 “No such event.”

Webhooks

Add the endpoint in the dashboard (Developers › Webhooks › Add endpoint) with Standard Webhooks and Test or Live, and tick the Accounts events. Sandbox events go to test endpoints, real ones to live endpoints. Endpoints can't be created by API in this phase.

  • Subscribing an endpoint in the current Vezmo format, or one without test/live, is 400 accounts_events_need_standard.
  • Before the Accounts API is on: 403 api_access_not_enabled. An unknown Accounts-looking name: 400 unknown_event_type. Removing Accounts events or changing the URL still works while access is off.
  • Up to 16 endpoints per environment; one more is 400 too_many_endpoints.
A delivery
POST /hooks/vezmo HTTP/1.1
Content-Type: application/json
webhook-id: evt_cm3k9r8te0007
webhook-timestamp: 1794650400
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
X-Webhook-Event: incoming.credited

Verify a webhook

webhook-signature is v1, + base64 HMAC-SHA256 of id.timestamp.body, keyed with the base64 after whsec_ in your signing secret. During a roll's overlap it carries two signatures, space-separated. Refuse a timestamp more than 5 minutes off, and use the raw body exactly as received.

Node.js (standardwebhooks)
// npm i standardwebhooks
import { Webhook } from "standardwebhooks";
import express from "express";

const wh = new Webhook(process.env.VEZMO_WEBHOOK_SECRET); // "whsec_…", as shown when you added the endpoint
const seen = new Set(); // use your database in production

const app = express();
app.post("/hooks/vezmo", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    // Checks the signature and refuses a timestamp more than 5 minutes off.
    event = wh.verify(req.body.toString("utf8"), {
      "webhook-id": req.get("webhook-id"),
      "webhook-timestamp": req.get("webhook-timestamp"),
      "webhook-signature": req.get("webhook-signature"),
    });
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(200); // answer within 15 s; do the work after
  if (seen.has(event.id)) return; // events can come twice
  seen.add(event.id);
  // Read the current state before acting on money, e.g. GET /transactions/{id}.
});
Node.js (no library)
// No library: the same check by hand.
import crypto from "node:crypto";

export function verifyVezmo(rawBody, headers, secret, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigs = String(headers["webhook-signature"] || "").split(" ");
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  // During a roll's overlap there are two signatures: either may match.
  return sigs.some((s) => {
    const [v, b64] = s.split(",");
    const got = Buffer.from(b64 || "", "base64");
    return v === "v1" && got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}
Python (standardwebhooks)
# pip install standardwebhooks   (Flask example)
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["VEZMO_WEBHOOK_SECRET"])  # "whsec_..."
app = Flask(__name__)

@app.post("/hooks/vezmo")
def vezmo():
    try:
        event = wh.verify(request.get_data(as_text=True), dict(request.headers))
    except Exception:
        return "", 400
    # dedupe on event["id"], then read the current state before acting on money
    return "", 200
PHP (standard-webhooks)
<?php
// composer require standard-webhooks/standard-webhooks
$wh = new \StandardWebhooks\Webhook(getenv('VEZMO_WEBHOOK_SECRET')); // "whsec_..."
try {
    $event = $wh->verify(file_get_contents('php://input'), [
        'webhook-id'        => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
        'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
        'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
    ]);
} catch (\Exception $e) {
    http_response_code(400);
    exit;
}
http_response_code(200);

Replies and retries

  • Answer any 2xx within 15 seconds.
  • 10 attempts, ±10% jitter: at once, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h, 24 h (about 3 days). Retry-After on a 429 or 503 is honoured, up to 24 h.
  • TEST endpoints: their own queue, 5 s per attempt and 3 attempts in all (now, 5 s, 5 min). A webhook.test or any test-mode event goes this way to any endpoint, live ones included.
  • Access switched off: queued Accounts deliveries stop; test events still go; resending an Accounts event is 403 api_access_not_enabled.
  • Accounts deliveries and test events leave the delivery log after 30 days.
  • 410 Gone switches the endpoint off at once (we email you). 50+ failures in a row over 3+ days switch it off too. Fill gaps from GET /events (30 days).

Test events and sending again

  • Send a test event on the endpoint's row sends one signed webhook.test (one attempt). livemode follows the endpoint.
  • Send again in its deliveries sends the same event (same webhook-id, same body) once, up to 30 days back.
  • Send an Accounts event again on the endpoint's row takes an event id from the last 30 days and sends it to that endpoint once, even if it never got it. An event of the other environment is refused.
webhook.test
{
  "id": "evt_test_cm3ka1",
  "object": "event",
  "type": "webhook.test",
  "apiVersion": "2026-11-14",
  "createdAt": "2026-11-14T10:05:00.000Z",
  "livemode": false,
  "data": { "object": { "endpointId": "cm3k…", "message": "This is a test event from Vezmo." }, "previousStatus": null }
}