Concepts

Events

The shape of a Kestrel event, how types are named, and what ordering guarantees you get.

Events

An event is an immutable record that something happened. Kestrel stores it, fans it out to your subscriptions, and keeps the delivery history for your plan's retention window.

Anatomy

{
  "id": "evt_01HZX9K2QW",
  "type": "invoice.paid",
  "streamKey": "customer_9f2a",
  "createdAt": "2026-08-24T09:14:22.481Z",
  "apiVersion": "2026-06-01",
  "payload": {
    "invoiceId": "in_1024",
    "amountCents": 4900,
    "currency": "usd"
  }
}

Field	Type	Notes
`id`	string	Prefixed `evt_`, 26 characters, lexicographically sortable by time.
`type`	string	Lowercase, dot-separated, max 3 segments.
`streamKey`	string	Optional. Events sharing a key are delivered in order.
`createdAt`	string	RFC 3339, millisecond precision, always UTC.
`apiVersion`	string	The version pinned on the key that published the event.
`payload`	object	Your data. Must be a JSON object, not an array or scalar.

Naming types

Event types are lowercase and dot-separated, with at most three segments — invoice.paid, user.subscription.cancelled. Kestrel rejects a type with four or more segments with 422 invalid_event_type.

Type names are case-sensitive on the wire but subscriptions match case-insensitively, so a subscription to Invoice.Paid receives invoice.paid.

Ordering

Events that carry the same streamKey are delivered to a given endpoint in the order they were published. Events with different keys, or with no key at all, have no ordering guarantee relative to each other.

Ordering is per endpoint, not global. If one endpoint is retrying an event, later events on the same stream key queue behind it for that endpoint only — other endpoints keep receiving normally.

Size

A single event payload may be up to 256 KB once serialized. Larger payloads are rejected with 413 payload_too_large. Store the body elsewhere and send a reference if you need to move more than that.

Retention

Plan	Event retention	Delivery log retention
Free	7 days	7 days
Team	60 days	60 days
Enterprise	90 days	90 days

Retention is enforced by a nightly job that runs at 03:00 UTC. See Limits and quotas for the full table.