Event Catalog

The common envelope

Every event Listo delivers is a single HTTP POST whose body is a DomainEvent envelope (no outer wrapper):

{
  "id": "lglsoevt_…",
  "type": "client.created",
  "specVersion": 1,
  "dataVersion": 1,
  "occurredAt": "2026-05-02T10:14:32.184Z",
  "entity": { "type": "client", "id": "lglsocli_…" },
  "data": { /* type-specific — see the per-event pages */ }
}

Top-level fields are identical across every type. data is the only field whose shape changes from one type to the next. See Overview → Anatomy of a delivery for the full envelope definition and header reference.

Catalog

The list will grow over time. Subscribe to all if you want forward-compatible coverage without coordinating a Listo-side update each time a new type lands. See Subscribing → Choosing event types.

Public ID prefixes you'll see

All identifiers in event payloads are opaque strings — never parse them. The prefixes are stable and useful for routing in your code:

workerId is per-client: the same physical person engaged at two different clients has two distinct Worker rows and two distinct workerId values. Use workerProfileId when you need to deduplicate a person across clients.

Cross-cutting semantics

These properties apply uniformly across every event type. The per-event pages reiterate them in context, but the canonical statement lives here.

Snapshot semantics (every embedded payload)

Every embedded data field is a snapshot at emit time. If the source record is edited between Listo emitting the event and your handler running it — typical for retries or a delayed consumer — the snapshot may not reflect the current state.

When you need fresh data:

GET https://gateway.listoglobal.com{data.links.self}
x-api-key: <your-key>

The path in data.links.self is already substituted with your installation's instanceIntegrationId before Listo signs the body, so you can call it as-is. Other path segments (clientId, workerId, …) are inlined too; only the instanceIntegrationId placeholder is ever rewritten by Listo.

Nested resources (workers under a client, contracts under a worker that aren't directly on the event, organization structure) are not embedded in any event payload. Pull them on demand via the public REST API.

Fan-out

The number of deliveries a single source change produces depends on the event type:

workerProfileId is the join key for treating multiple worker.updated deliveries (or a worker.onboarded followed by later worker.updateds) as the same physical person.

Mutual exclusion: worker.onboarded ↔ worker.contract.updated

These two events are mutually exclusive at the source for a single status transition: when a contract moves to EXECUTED for the first time on a (worker, client) pair, you receive worker.onboarded and not the worker.contract.updated that would otherwise fire for that status change. Subsequent contract changes (later EXECUTED transitions on additional contracts for the same pair, job-title edits, manager changes) emit worker.contract.updated as normal.

Don't double-handle a single EXECUTED transition by listening for both events — Listo enforces the suppression at the producer side.

Idempotency and ordering apply universally

These rules are the same for every type:

• Duplicates are normal. Listo retries up to 3 times on non-2xx, network error, or timeout. Dedupe on webhook-id (= the body's top-level id).
• Order is not guaranteed — across types, across entities, or even within a single entity. Use occurredAt to order on your side if order matters. A worker.updated may arrive before the corresponding worker.onboarded; a child entity event may arrive before its parent. Tolerate it.

See Delivery & retries for the full contract.

Versioning

• Envelope version (specVersion): bumps only on breaking changes to the envelope itself (rename of type, structural changes to the outer object). Currently 1.
• Per-type data version (dataVersion): bumps independently when a single event type's data shape breaks. Each type owns its own lineage.
• Additive changes (new optional data fields, new event types) do not bump anything. Your handler must tolerate unknown fields and unknown types gracefully.

Pin your verification logic against the (type, dataVersion) pair, not specVersion alone. See Overview → Versioning policy.

"Which event should I listen to?"

A quick decision guide, by use case:

Per-event references

• client.created
• user.created
• worker.onboarded
• worker.updated
• worker.contract.updated