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
A webhook delivery is the event's data object as the JSON body, with the rest of the event in headers:
| You get | Where | What it gives you |
|---|---|---|
| The event id | X-Revenexx-Event-Id header | A stable unique id — your deduplication key. |
| The topic | X-Revenexx-Topic header | What happened: the event's topic. |
| The payload | the body | The event's data, shaped by the topic. |
| Metadata | one X-Revenexx-<key> header per key | Context, such as where it came from. May be none. |
Two parts of the event envelope do not arrive: the event's time and its tenant_id. The X-Revenexx-Timestamp header is when that delivery attempt was sent, not when the event happened, and it changes on every retry.
That matters for reporting. For an event-time axis, use the entity's own timestamp, from data where the topic carries one or from re-reading the entity through the API, and store your arrival time separately for diagnosing lag. The event id is what makes a handler idempotent, which you need because delivery is at least once. And because a delivery does not name its tenant, give each tenant its own endpoint URL; see Register an endpoint.
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
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 retry window.
- Events — the platform service in full.
- Pull versus push — where the stream fits against reading the API.