Events

React to what happens on the platform. Every meaningful change emits an event you can subscribe to.

Things happen on your tenant all the time: an order is created, a customer is activated, stock changes, a price is updated. Each of those is an event — a small, structured record of something that occurred, published the moment it happens. The event stream is how your code finds out, without polling and without the part of the platform that changed having to know you exist.

You don't read the stream over a raw connection. You react to it two ways:

From an App — declare which events your app subscribes to, and the platform runs your handler when one arrives. This is how apps stay loosely coupled: a publisher emits order.created and never has to know who listens.
At your own HTTP endpoint — register a Webhook and the platform delivers matching events to your URL, signed so you can verify they're genuine.

Both react to the same stream. Pick the App handler when the reaction lives inside Revenue Cloud; pick a Webhook when the reaction lives in your own infrastructure.

What an event looks like

Every event the platform publishes shares one envelope. The shape is fixed — it's the contract you build against:

Event envelope

{
  "tenant_id": "acme-eu",
  "topic": "order.created",
  "id": "evt_01jc8m4yq2…",
  "data": { "order_id": "o_8421", "total": 14990, "currency": "EUR" },
  "metadata": { "source": "checkout" },
  "time": "2026-05-31T10:00:00Z"
}

Field	Type	What it is
`tenant_id`	string	The tenant the event belongs to (your tenant slug).
`topic`	string	What happened, e.g. `order.created`. See Event types.
`id`	string	A stable, unique id for this event. Use it to deduplicate.
`data`	object	The payload. Its fields depend on the topic.
`metadata`	object	Context about the event, such as where it came from. May be empty.
`time`	string	ISO-8601 UTC instant the event occurred.

data and metadata are always JSON objects. An empty one is {}, never null and never an array.

Topics name what happened

A topic is a dot-separated name in resource.action form — order.created, customer.activated, inventory.stock_changed. The first segment is the thing, the rest is what happened to it. Apps that publish their own events use a longer namespaced form so names never collide; see Event types.

You subscribe by topic. An App lists the topics it wants in its manifest; a Webhook destination is configured with the topics it should receive. Either way, you only get the topics you ask for.

Delivery you can rely on

Events are delivered at least once. The platform keeps trying until your handler or endpoint accepts the event, which means a transient failure on your side doesn't lose the event — but it also means the same event can arrive more than once. Build handlers to be idempotent: key off the event id and ignore one you've already processed.

Order is best-effort, not guaranteed. Don't assume order.paid always lands after order.created; use the data and time fields to reconstruct sequence when it matters.

What's in this section

Event types — how topics are named, the shape of payloads, and where to find the exact catalog for your tenant.
Consuming events — the two ways to react: App handlers and Webhooks, and how to choose.

Where to go next

Webhooks — deliver events to your own HTTP endpoint, with signature verification.
Apps — build installable logic that publishes and subscribes to events inside Revenue Cloud.
Integration Studio — when an event should trigger a durable workflow against an external system.

Was this page helpful?