Skip to main content

Events

An event is a record of something that happened in your Tenant: a token was created, a Proxy call completed, a Reactor failed, a Network Token was updated. Every event carries its type, when the operation happened, the Tenant, a trace ID that correlates it with related events, and a data payload describing the affected resource and, when known, the actor that caused it. Event Types lists every event and its payload.

Basis Theory exposes events in two ways:

  • Query Events returns your Tenant's event history on demand, newest first, filtered by time range, event type, trace ID, and exact values inside the payload. Use it for debugging, observability, and auditing activity within your Tenant. The rest of this page describes this API.
  • Webhooks push each event to your endpoint as it happens. Use them to react in real time or to ingest events into your own telemetry and monitoring systems.

Events become searchable shortly after they occur, typically within 30 seconds. An event can be delivered through Webhooks before it is available to query. Both channels carry the same event object; a Webhook wraps it in a delivery that adds delivered_at.

Authentication​

Send the API key of a Management Application that has the event:read permission in the BT-API-KEY header. The Tenant is always taken from the credential; there is no Tenant parameter. See Authentication for how API keys are sent.

Retention​

Your Tenant's Log Retention quota sets how much history you can search. The default is 24 hours. Basis Theory can raise it on request up to the 30-day platform maximum; contact us to request a higher retention period. A single request never reaches more than 30 days back.

The API clamps a requested time range to the visible window instead of rejecting it. A start_date earlier than your searchable history becomes the oldest visible instant, and an end_date in the future becomes the time of the request. If nothing remains after clamping, for example when the whole range is older than your retention, the response is 200 with an empty page. One request can cover your entire searchable history, so you do not need to split it into smaller ranges.

Next Steps​

  • Query Events: the List Events endpoint, query parameters, payload filters, pagination, and errors.
  • List Reactor Logs and List Proxy Logs: individual runtime-log records for one Reactor or Proxy, searchable by message.
  • Event Types: the type and payload fields of every event, which are also the paths you can filter on.
Last updated on