The event stream
Every meaningful change on a tenant is published as an event: a small structured record of something that occurred. For analytics that makes the stream a change feed — the lowest-latency way to know that an order was placed, a cart was abandoned, a price moved.
The stream itself is a platform service. Events is the reference: the envelope, the topic naming, the delivery guarantees. This page is what it is worth to you when the goal is numbers.
What arrives
One fixed envelope, whatever the topic:
| Field | What it gives you |
|---|---|
id | A stable unique id — your deduplication key. |
topic | What happened, in resource.action form. |
tenant_id | Which tenant it belongs to. |
time | ISO-8601 UTC instant the event occurred — your event-time axis. |
data | The payload, shaped by the topic. |
metadata | Context, such as where it came from. May be {}. |
Two of those matter more than the rest for reporting. time is when it happened, which is not when it arrived — use it as the timestamp you store, so a retry or a delayed delivery does not smear your time series. id is what makes a handler idempotent, which you need because delivery is at-least-once.
What the stream is good for
- Freshness. A figure that has to be current within seconds.
- Reacting. An alert, a threshold, a notification — something that has to happen because of the event rather than in a report about it.
- Cheap change detection. Knowing which entities changed since you last looked, so a sync re-reads twenty records instead of twenty thousand. See Incremental sync.
What it cannot do
Two limits, and both catch people out:
It cannot answer for the past. A stream starts when you subscribe. There is no backlog to replay from before an endpoint existed, so your first quarter of history has to come from the API — see Backfill.
It is not a substitute for the entity. An event tells you that something happened and carries a payload about it; the payload is not a guarantee of the entity's full current state. Where a figure has to be right rather than fresh, re-read the entity through the API and let the event be the trigger for reading it.
The shape that works
event arrives → verify → dedupe on id → record (topic, id, time, data)
→ optionally re-read the entity from the API
→ update your own store
The stream is the notification; your store is the answer. Keeping that separation is what stops a missed delivery or an out-of-order arrival becoming a wrong number in a report — see Delivery guarantees.
Where to go next
- Event types for reporting — which topics to subscribe to.
- Delivery guarantees — at-least-once, ordering, and the delivery log.
- Events — the platform service in full.
- Pull versus push — where the stream fits against reading the API.