Platform Event

Why this catalogue lives on the platform, not in a tenant's own indexer#

The alternative to a platform-run catalogue is a tenant indexer running beside the platform: watching the same chain, choosing its own reorganisation depth, and turning raw logs into its own vocabulary. That second indexer answers the same question the platform already answers, from a read of the chain that only the tenant sees.

This catalogue holds no second reading, because the same indexer that decides a chain fact for the platform's own record is the one that derives the outbox row a subscriber later receives. The event and the indexed fact it describes come from that one decision, not from two.

A vocabulary that cannot move under you#

A platform event is one entry in a vocabulary defined by a single registry. Each entry binds an event name and version to one payload shape. The build rejects a second registration of the same name and version.

That guarantee targets the two quiet ways an integration built on notifications usually breaks. A field changes shape and the consumer keeps parsing the old one. Or a name starts covering a slightly different occurrence and nobody tells the consumers. Both fail silently, and a reconciliation turns them up weeks later.

The platform generates the machine-readable event manifest, event types for the TypeScript SDK, and sample payloads from that registry. The event catalogue is written by hand and checked against the registry. It explains when each event is sent and what a receiver does with it. Payload schemas and examples stay in the machine-readable definitions. Registration alone does not prove the platform sends an event. The catalogue separates live events from reserved names.

An integration selects the published payload contract by event name and version. Read both fields before interpreting the payload.

The envelope states how settled a fact is#

Every platform event has a lifecycle_state: pending, provisional, final, retracted, or recalled. Recalled is reserved. No live event uses it. Many names end in a state, such as token.transfer.final, but others end in a word such as raised or published. Read the envelope's state and event type together. The lifecycle reference describes the live sequences and reserved states.

For chain observations, provisional means included but still within the network's configured confirmation depth, and final means the source block has passed that depth. A platform administrator sets that depth for each network. The platform emits provisional at inclusion and final after the depth is reached. A chain reorganisation within the depth can retract a delivered provisional event. A reorganisation deeper than the configured depth is outside what a final event promises.

A fact does not change state in place. The same movement reported first as provisional and later as final reaches you as separate events with separate identifiers. Watch for the later event rather than for a field changing on the earlier one.

A retraction reports that an earlier fact no longer stands. It can follow a chain reorganisation or a business reversal, such as a trade bust. The platform leaves the earlier delivery intact. The consumer contract defines how to match the correction, including when its supersedes field is absent or names an event you never received.

Pending reports a transaction request that the platform broadcast and that is not confirmed. A request outcome uses final, including a failure or cancellation. This is the request's outcome, not a token movement's chain finality. Recalled is a reserved state, and no live event uses it.

From one log to one row per subscriber#

For an event derived from a chain log, the platform records one pending delivery for every endpoint whose subscription matches the event name, in the same database transaction as the indexed fact. No queue sits in memory between the two, so the event and the indexed state it describes commit together or not at all.

Transaction-request events describe a different source: a state change recorded inside the platform. The platform records the event together with that state change, rather than deriving it from an indexed chain log.

The fan-out is per subscriber, not per fact. Ten subscribed endpoints mean ten rows from one log, each signed on its own and each with its own identifier, so one endpoint's delivery history says nothing about another's.

Every subject area the indexer writes, token movements and identity and role changes alike, handles a failure to write those rows the same way. A failure to record the deliveries blocks the indexed write, so the whole unit retries together. When the retry succeeds, the indexed change and its notification land in that same commit, so a caller never sees one without the other. No gap can open between the indexed fact and its recorded delivery, and Webhook Delivery moves that delivery to your endpoint. The cost is that a delivery-recording problem delays the indexed record too.

Each endpoint has its own delivery sequence. A later eligible event waits while an earlier event remains pending, including during retry backoff. A linked correction waits until its cause was delivered or can no longer be delivered. Events waiting for chain finality do not block later events. A Replay can deliver an older observation after a newer one, so keep the newest state you hold. The ordering contract states the limits.

Writing a consumer that stays correct#

A correct consumer subscribes only to the states it handles, deduplicates on the event identifier, and applies a superseding event by looking up the identifier that event names instead of assuming order.

An endpoint subscribes with patterns. A pattern matches a name prefix, as in token.transfer.*, a name suffix, as in *.final, or one exact name. The defaults match names ending in .provisional, .final, and .retracted, not the envelope's lifecycle state. The subscriptions reference lists live events these defaults skip. A *.pending pattern delivers nothing, because no live event name ends in .pending. A subscription change replays no earlier events. Replay is a separate request.

The webhook-id header carries the event identifier. Store each identifier and check it before you act. Delivery, the signed HTTPS POST that carries one event to one subscribed endpoint, uses bounded retries: a retry after a lost acknowledgement can repeat a delivery your endpoint already processed. Nothing on the platform side deduplicates for you.

Treat an event as an append-only record rather than as an update. When a later event supersedes an earlier one, it includes a supersedes field naming the identifier it replaces, and the platform never rewrites the original delivery. That field holds one identifier, never a list, so a superseding event always points at exactly one predecessor. A consumer that applies a retraction by looking up the superseded identifier and reversing its effect stays correct through a reorganisation. A consumer that overwrites in place cannot tell the difference between a correction and a fresh occurrence.

The platform publishes machine-readable definitions as a subscription manifest, the DALP events manifest, with a version marker that identifies the inventory it describes. Pin that marker if you generate code from the manifest, so an inventory change is a decision you make rather than one that arrives during a deploy.

Frequently asked questions#