API Reference

Events

Every state change your integration cares about, delivered by webhook and queryable for 90 days.

Events are delivered by webhook and are also queryable at GET /events (90-day retention) — the same envelope on both, so dedupe by id. The data object is a thin id + minimal-state projection; fetch full detail back through the authenticated read API.

delivery envelope

{
  "data": {
    "currency": "USD",
    "invoice_id": "inv_8fq2Lm",
    "number": "INV-1042",
    "status": "paid",
    "total_cents": 150000
  },
  "id": "evt_2aQ9xL",
  "occurred_at": "2026-01-15T09:30:00Z",
  "type": "invoice.paid",
  "version": 1
}

invoice.overdue

A sent invoice passed its due date without being paid.

invoice.overdue · data

{
  "invoice_id": "inv_8fq2Lm",
  "number": "INV-1042",
  "status": "overdue",
  "total_cents": 150000,
  "currency": "USD"
}

invoice.paid

An invoice was paid in full (terminal — after any provisional clearing window).

invoice.paid · data

{
  "invoice_id": "inv_8fq2Lm",
  "number": "INV-1042",
  "status": "paid",
  "total_cents": 150000,
  "currency": "USD"
}

invoice.sent

An invoice was sent to its recipient.

invoice.sent · data

{
  "invoice_id": "inv_8fq2Lm",
  "number": "INV-1042",
  "status": "sent",
  "total_cents": 150000,
  "currency": "USD"
}

invoice.voided

An invoice was voided and is no longer payable.

invoice.voided · data

{
  "invoice_id": "inv_8fq2Lm",
  "number": "INV-1042",
  "status": "voided",
  "total_cents": 150000,
  "currency": "USD"
}

payment.canceled

A payment was canceled and will not proceed.

payment.canceled · data

{
  "payment_intent_id": "pi_3Nk2Ht7Qz",
  "amount_cents": 42000,
  "currency": "USD"
}

payment.completed

A payment completed (settled).

payment.completed · data

{
  "payment_intent_id": "pi_3Nk2Ht7Qz",
  "amount_cents": 42000,
  "currency": "USD"
}

payment.failed

A payment failed and did not move money.

payment.failed · data

{
  "payment_intent_id": "pi_3Nk2Ht7Qz",
  "amount_cents": 42000,
  "currency": "USD"
}

payment.held

A payment is held awaiting approval or step-up before it can proceed.

payment.held · data

{
  "payment_intent_id": "pi_3Nk2Ht7Qz",
  "amount_cents": 42000,
  "currency": "USD"
}

test.event

A test event sent on demand to verify an endpoint's delivery and signature handling.

test.event · data

{
  "message": "This is a test event."
}

GET/api/ext/v1/events

List events

Parameters

Name	In	Type	Description
types	query	string	Comma-separated public event types to include (default: all).
limit	query	integer	Page size (default 50, max 100).
starting_after	query	string	Event id cursor — returns events older than it.

Responses

200Your organization's events, newest first, queryable for 90 days — the same envelopes webhooks deliver (dedupe by id).

Field	Type	Description
datarequired	PublicEnvelope[]	The page of events, newest first.
has_morerequired	boolean	Whether another page exists; page with starting_after=<last id>.

200 example

{
  "data": [
    {
      "data": {
        "currency": "USD",
        "invoice_id": "inv_8fq2Lm",
        "number": "INV-1042",
        "status": "paid",
        "total_cents": 150000
      },
      "id": "evt_2aQ9xL",
      "occurred_at": "2026-01-15T09:30:00Z",
      "type": "invoice.paid",
      "version": 1
    }
  ],
  "has_more": false
}

Errors

400Unknown event type, bad limit, or unknown starting_after id

401Missing or invalid API token

403Token lacks the required scope or credential class

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/events \
  -H "Authorization: Bearer $BOB_API_TOKEN"

GET/api/ext/v1/events/{eventId}

Get an event