Events

Overview

Each change Tavrn announces (a retrieval status change, an action request, new documents, an endpoint being disabled) is an event. Events are delivered to your webhooks and, independently, written to an event log you can read with GET /v2/events for 30 days. The event body is identical in both places: the id, type, created_at and data you see in a webhook delivery are the same values GET /v2/events/{id} returns.

Event object

{
  "id": "rr-06a28fdc7a8abfa2a1c98dd0562020ebb41ca740377930a736854d23a6c9881a",
  "object": "event",
  "type": "retrieval_request.status_changed",
  "created_at": "2026-02-01T14:22:10.000Z",
  "api_version": "v2",
  "request_id": null,
  "data": {
    "retrieval_request_id": "507f1f77bcf86cd799439011",
    "case_id": "507f1f77bcf86cd799439012",
    "public_updated_at": "2026-02-01T14:22:10.000Z",
    "status": "processing",
    "stage": "request_sent",
    "action_required_reason": null
  }
}

Field	Description
`id`	Deterministic event ID. Equals the webhook body `id` and the `X-Webhook-Event-Id` header.
`type`	Event type. See the per-type `data` shapes in the webhooks guide.
`created_at`	When the triggering change was saved.
`api_version`	API version the event was rendered with.
`request_id`	Request ID of the API call that caused the event, or `null`.
`data`	Event payload; same as the webhook body `data`.

Listing events

curl "https://enterprise.tavrn.ai/v2/events?type=retrieval_request.action_required&created_after=2026-02-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer tavrn_sk_live_..."

Filters: type (comma-separated, up to 20), created_after, created_before, object_id (for example a retrieval request ID). Results are newest first; follow next and previous for pagination. Scopes. webhooks:read plus the read scope of the event family — retrievals:read for retrieval_request.*. Events from families your key cannot read are omitted; asking for one explicitly with type returns 403 insufficient_scope.

Reconciliation after an outage

Note the created_at of the last event you processed.
GET /v2/events?created_after=<that time> and page through next.
Process each event as you would a webhook delivery, deduplicating on id.

The event log covers 30 days. For anything older, use incremental polling on the resource itself.

GET /v2/webhooks/{id}/deliveries — what happened to each delivery attempt.
Redeliver — send an event to your endpoint again.

Get started

Retrieval reference

Case documents

Overview

Event object

Listing events

Reconciliation after an outage

​Overview

​Event object

​Listing events

​Reconciliation after an outage

​Related

Overview

Event object

Listing events

Reconciliation after an outage

Related