What an event is
An event is a past fact. It records something that already happened and cannot be rejected, retried or argued with — stop.completed means the stop was completed, not that completing it has been requested.
That shape has two consequences worth knowing before you build against it:
- Events fan out. Any number of subscribers can receive the same event, and Mesh does not care who is listening. Adding a subscriber changes nothing for the others.
- Events are never replayed as instructions. If you need to make something happen, call the API. Events are the outbound half of the platform only.
The platform also runs a command surface (loc_mesh.commands.*) for imperative intents consumed by exactly one handler. It is internal plumbing and is not exposed to tenants — nothing on it reaches your webhook, and you cannot subscribe to it. Everything in these docs is the events surface.
The envelope
Every event, of every type, arrives wrapped in the same envelope. The fields below are the contract; the per-event payload sits inside payload and varies by event_type.
| Field | Type | Required | Notes |
|---|---|---|---|
| event_id | string uuid | ✓ | Unique per event. Consumers may dedup on this. |
| event_type | string | ✓ | Dotted, lowercase discriminator: stop.completed, run.started, package.moved, ... Drives which branch of the `payload` union is set. The canonical name consumers key on (the PascalCase Avro record name is the same event by form only — see the generated eventTypes map). |
| aggregate_type | string | ✓ | stop, run, order, package, user, note, ... Stable per producing context. (Driver is not its own aggregate — driver identity rides as an optional driver_id on the relevant payloads.) |
| aggregate_id | string | ✓ | Kafka partition key. Same field set by the Outbox SMT as the message key. |
| version | long | ✓ | Monotonic per-aggregate sequence. Hot-cache CAS compares incoming > stored. |
| tenant_id | string | ✓ | Tenant scope for downstream routing and authorisation. |
| occurred_at | long timestamp-millis | ✓ | Wall-clock at which the writer committed. NOT the ordering key — use `version`. |
| correlation_id | string | null uuid | — | Trace ID propagated from the originating request. |
| client_correlation_id | string | null | — | Optional opaque client-supplied correlation id (X-Correlation-Id). Passthrough only — never used for auth/routing/dedup. |
| causation_id | string | null uuid | — | The event or command that caused this one, if any. |
| payload | union | — | Per-event-type record. The union extends as new event types are added in schemas/<context>/*.avdl. Adding a branch is BACKWARD-compatible. |
occurred_at is wall-clock at the writer and is useful for display, not for sequencing. version is a monotonic per-aggregate counter — compare it, not timestamps, when you decide whether an event is newer than the state you hold.
How delivery works
Events are published to Kafka by the service that owns the change. From there:
- A processor matches the event against the active subscriptions for that tenant.
- A dispatcher signs the body with that subscription’s secret and POSTs it to your URL.
- Your endpoint answers. A 2xx ends the delivery; anything else decides whether it is retried.
Retries
| Your response | What happens |
|---|---|
| 2xx | Delivered. Nothing further. |
| 5xx, 429, or a network failure | Retried with exponential backoff — 1s, then 3s, then 9s. After the last attempt the delivery goes to the dead-letter queue. |
| Any other 4xx | Dead-lettered immediately, with no retry. A 4xx says the request was wrong, and sending the identical request again cannot fix that. |
The dispatcher is waiting on your response. Return 200 as soon as you have the event safely written down, then do the real work out of band. An endpoint that processes synchronously turns a slow database into retries and, eventually, dead-lettered events.
Ordering and duplicates
Expect duplicates
Delivery is at-least-once. A retry that your endpoint actually received but failed to acknowledge in time arrives again, and the second copy is identical to the first. event_id is unique per event and stable across retries — key your idempotency on it.
Expect reordering across aggregates
Ordering holds per aggregate: two events for the same aggregate_id carry increasing version numbers. Across different aggregates there is no ordering guarantee at all, and retries can make that visible — a retried stop.arrived can land after a first-try stop.completed for a different stop.
Deduplicate on event_id. Order on aggregate_id + version. Treat an event whose version is not greater than what you already stored as something you have already handled.
What is live today
The mechanism and the catalogue are at different stages, and it is worth being precise about which is which.
- The delivery pipeline is built. Subscriptions, HMAC signing, retry and dead-lettering all work as described above.
- The catalogue is complete as a contract. All 33 event types across 7 topics have registered schemas, so the envelope and payload you will receive are settled.
- Which events actually reach you depends on your modules. An event only flows if the module that raises it is live and enabled on your account. Several modules are still Planned — their event types are documented so you can build against them, but nothing emits them yet.
Each module page lists the events that module raises, and carries its own availability label. That is the place to check whether a given event type is something you can receive today.
GPS telemetry is a separate surface
Live driver positions do not arrive as domain events. Position fixes stream from the mobile app at a volume that would swamp a webhook endpoint, so they travel on their own telemetry topic and are read rather than pushed:
- Current position — read the snapshot endpoint on the tracking API. Sub-millisecond, served from cache.
- Where a driver has been — read the bounded history endpoint over a time window.
What does arrive as an event is the meaning derived from those positions — geofence.entered and geofence.exited are raised when a tracked subject crosses a boundary you defined. See Realtime GPS Tracking and Geofences.
That is the geofence pattern: define the boundaries that matter to you and subscribe to the crossings. Subscribing to raw position fixes is not offered, because at one fix per driver every few seconds it would be a denial-of-service against your own endpoint.
Where to go next
- The event catalog — every event type, grouped by topic, with its payload fields.
- Managing subscriptions — registering a webhook URL, choosing event types, rotating secrets.
- Verifying signatures — what X-Mesh-Signature is and exactly how to check it.