# Events (/reference/events)

## What changed since you last asked — for polling instead of webhooks

`GET /v1/changes`

One call for a cron job: every invoice, deposit, payout, customer and wallet an event touched after your cursor, each reduced to its LATEST state (the same shape its `GET` returns). Available on every plan, including the ones without webhooks.

First call: send nothing (the whole log, oldest first) or `since=<ISO instant>`. Every call after that: send back the `next_after` you were given as `after`. The cursor is the event `sequence` — ordered, gap-tolerant, and the same number a webhook envelope carries, so moving to webhooks later reconciles against the same axis.

`has_more: true` means the page filled before the log ran out: call again immediately with the new `next_after` rather than waiting for the next tick. The defaults scan 200 events a call, at most 500.

A resource touched five times in the window appears once, with `last_event` saying which event that was — an invoice created, quoted and paid between two polls comes back as one paid invoice.

### Parameters

- `after` (query, optional, integer) — The `next_after` from your previous call. Omit on the first call.
- `since` (query, optional, string (date-time)) — First call only: everything after this instant. Ignored when `after` is given.
- `limit` (query, optional, integer) — Events scanned per call, not resources returned.
- `type` (query, optional, array, of string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — Only these event types. Repeatable.

### Responses

- `200` — What changed, grouped and reduced to latest state.
  - `object` (required, string)
  - `livemode` (required, boolean)
  - `invoices` (required, array) — Invoices touched, latest state each. Refund events land here too — they are about the invoice.
    - `id` (required, string) — The resource's public id — the same id its `GET` takes.
    - `last_event` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — The event that last touched it.
    - `sequence` (required, integer) — That event's `sequence`.
    - `updated` (required, string (date-time))
    - `data` (required, object) — The resource as its `GET` returns it, from the last event.
  - `deposits` (required, array)
    - `id` (required, string) — The resource's public id — the same id its `GET` takes.
    - `last_event` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — The event that last touched it.
    - `sequence` (required, integer) — That event's `sequence`.
    - `updated` (required, string (date-time))
    - `data` (required, object) — The resource as its `GET` returns it, from the last event.
  - `payouts` (required, array)
    - `id` (required, string) — The resource's public id — the same id its `GET` takes.
    - `last_event` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — The event that last touched it.
    - `sequence` (required, integer) — That event's `sequence`.
    - `updated` (required, string (date-time))
    - `data` (required, object) — The resource as its `GET` returns it, from the last event.
  - `customers` (required, array)
    - `id` (required, string) — The resource's public id — the same id its `GET` takes.
    - `last_event` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — The event that last touched it.
    - `sequence` (required, integer) — That event's `sequence`.
    - `updated` (required, string (date-time))
    - `data` (required, object) — The resource as its `GET` returns it, from the last event.
  - `wallets` (required, array)
    - `id` (required, string) — The resource's public id — the same id its `GET` takes.
    - `last_event` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test) — The event that last touched it.
    - `sequence` (required, integer) — That event's `sequence`.
    - `updated` (required, string (date-time))
    - `data` (required, object) — The resource as its `GET` returns it, from the last event.
  - `other` (required, array) — Events whose `data` is not a resource with a stable `GET` shape (balance transfers, conversions, own-wallet moves, endpoint tests), as raw events.
    - `object` (required, string)
    - `id` (required, string)
    - `type` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test)
    - `api_version` (required, string)
    - `created` (required, string (date-time))
    - `livemode` (required, boolean)
    - `tenant` (optional, string (uuid))
    - `sequence` (required, integer) — Monotonic per project, with gaps. The list is ordered by it.
    - `resource_id` (required, string) — The id of the resource in `data` (a deposit, a payout, an endpoint…).
    - `data` (required, object) — The resource, identical to its REST GET shape.
  - `events_scanned` (required, integer)
  - `has_more` (required, boolean) — True when more events follow `next_after`. Call again at once rather than waiting for the next cron tick.
  - `next_after` (required, integer) — Store this and send it back as `after` on the next call. Unchanged when nothing happened.
- `400` — `invalid_query`.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Every event your project emitted, newest first

`GET /v1/events`

Ordered by `sequence`, the same number the webhook envelope carries — so reconciling "did we miss one?" is a comparison against this list. `type` may be repeated.

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.
- `type` (query, optional, array, of string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test)
- `resource_id` (query, optional, string) — The deposit, payout, customer… the event is about.

### Responses

- `200` — Events.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string)
    - `type` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test)
    - `api_version` (required, string)
    - `created` (required, string (date-time))
    - `livemode` (required, boolean)
    - `tenant` (optional, string (uuid))
    - `sequence` (required, integer) — Monotonic per project, with gaps. The list is ordered by it.
    - `resource_id` (required, string) — The id of the resource in `data` (a deposit, a payout, an endpoint…).
    - `data` (required, object) — The resource, identical to its REST GET shape.
- `400` — `invalid_query` — an unknown event type.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Your events as they happen (Server-Sent Events)

`GET /v1/events/stream`

A `text/event-stream` for dashboards and point-of-sale screens; webhooks remain the delivery contract for your backend. Frames: `ready` once with `{cursor}`; `event` with `{id, type, created, livemode, scope, data}` — `scope: "account"` carries the same `data` as `GET /v1/events`, `scope: "funding"` is a deposit to one of your funding addresses (`GET /v1/billing/funding`), trimmed to the transfer; `billing` with `{id, kind, amount_cents, note, chain, asset, created}` for each billing-ledger line; `ping` every 25 s. Every `event`/`billing` frame has an SSE `id`: send it back as `Last-Event-ID` to resume (replay is limited to the last 10 minutes). Streams close after 30 minutes; reconnect. At most 10 open streams per project.

### Parameters

- `Last-Event-ID` (header, optional, string) — The last frame `id` you received — resume after it.

### Responses

- `200` — The stream.
  string
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — `rate_limited`, or `too_many_streams` — already at the per-project stream limit.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## GET /v1/events/{id}

`GET /v1/events/{id}`

### Parameters

- `id` (path, required, string) — `evt_…`

### Responses

- `200` — The event, `data` included.
  - `object` (required, string)
  - `id` (required, string)
  - `type` (required, string, one of: customer.created, wallet.created, deposit.detected, deposit.confirmed, deposit.failed, deposit.orphaned, payout.created, payout.approved, payout.rejected, payout.submitted, payout.confirmed, payout.failed, payout.canceled, balance.transferred, balance.transfer_reversed, own_wallet.transferred, conversion.completed, conversion.failed, invoice.created, invoice.pending, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.canceled, invoice.refund_requested, invoice.refunded, invoice.refund_failed, billing.balance_low, billing.balance_exhausted, billing.auto_topup, relay.rent_created, relay.credit_detected, relay.credit_forwarded, relay.credit_fallback, relay.rent_expiring, endpoint.test)
  - `api_version` (required, string)
  - `created` (required, string (date-time))
  - `livemode` (required, boolean)
  - `tenant` (optional, string (uuid))
  - `sequence` (required, integer) — Monotonic per project, with gaps. The list is ordered by it.
  - `resource_id` (required, string) — The id of the resource in `data` (a deposit, a payout, an endpoint…).
  - `data` (required, object) — The resource, identical to its REST GET shape.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Where each send of this event stood

`GET /v1/events/{id}/deliveries`

One row per endpoint per (re)send. Not paginated — an event has a handful.

### Parameters

- `id` (path, required, string)

### Responses

- `200` — Deliveries, newest first.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string)
    - `tenant_id` (optional, string (uuid))
    - `event_id` (required, string)
    - `endpoint_id` (required, string (uuid))
    - `event_type` (optional, string | null)
    - `endpoint_url` (optional, string | null)
    - `status` (required, string, one of: pending, succeeded, failed, exhausted, skipped, canceled) — `pending` is queued or between retries; `exhausted` ran out of attempts; `skipped` was recorded while the endpoint was paused or disabled and is the gap you replay; `failed` is terminal without retry (a 410, or the URL failed the send-time check).
    - `attempt` (required, integer) — Attempts made so far.
    - `max_attempts` (required, integer)
    - `next_attempt_at` (optional, string | null (date-time))
    - `response_status` (optional, integer | null) — The receiver's HTTP status on the last attempt.
    - `resolved_ip` (optional, string | null) — The address the last attempt connected to.
    - `duration_ms` (optional, integer | null)
    - `error_detail` (optional, string | null) — Why the last attempt did not succeed, in our words.
    - `replay_of` (optional, string | null) — Set on a replay: the delivery it re-sends. The EVENT id is unchanged.
    - `delivered_at` (optional, string | null (date-time))
    - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.