Source: https://dinakar-pageloop-knowledge-base.docs-staging.pageloop.ai/concepts/events

# Events

# 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 30 days.

## Anatomy

```json
{
  "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`.

> [!INFO]
>
> 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.

> [!WARNING]
>
> 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       | 30 days         | 30 days                |
| Enterprise | 90 days         | 90 days                |

Retention is enforced by a nightly job that runs at 03:00 UTC. See
[Limits and quotas](/reference/limits-and-quotas) for the full table.