Choose an event surface

This page is for developers and solution architects deciding how their code should find out that something happened on a tenant — an order placed, a product changed, an App installed. By the end you'll know which surface to build on for each reaction in your design, and which page to read next.

Everything starts from one place. The platform publishes a single event stream: every meaningful change emits an event, and you don't read that stream over a raw connection. You pick a consumer for it. There are three, and the reporting pages under Analytics describe a fourth use of the first one rather than a separate mechanism.

The short answer

• You need an answer now, or the current state of something? Don't use an event. Call the API. Events are fire-and-forget reactions to something that already happened.
• The reaction runs in your own infrastructure, such as your server, your queue or your search index? Use a webhook.
• The reaction is an integration: push this change into another system, as a durable multi-step flow, with no server of your own? Use an Integration Studio event trigger.
• The reaction is logic inside your App? An App handler, but only app.installed and app.uninstalled are verified (as of 2026-09). See below.
• You're feeding dashboards or a warehouse? A webhook into your own store for freshness, plus reading the API for completeness. Push alone is the one to avoid.

Side by side

Whichever you pick, design the handler for duplicates and for events out of order. Webhooks and workflow triggers are delivered at least once, so the same event can arrive twice, and neither guarantees order, so don't assume order.paid lands after order.created. For an App handler even the delivery guarantee isn't documented (as of 2026-09).

A webhook

A webhook is for code you run yourself. The platform POSTs each event on the topics you chose to an HTTPS endpoint you registered in Cockpit, and your server does whatever comes next: update your ERP, purge a cache, send a notification.

It is the right choice when the reaction already lives outside Revenue Cloud, or when you want the event in a system you control. You own the endpoint, its uptime and its de-duplication. Before acting on a delivery, verify it came from the platform. What arrives in a delivery is on Webhooks, how to check it is on Security, and what happens when your endpoint fails is on Delivery.

Choose it when the reaction already lives outside the platform, or you want the event in a store you control. Don't use it when the reaction belongs inside the platform. That is an App's job, or a workflow's.

An Integration Studio event trigger

An event trigger starts a workflow when an event fires. It is how you subscribe from a workflow instead of writing a listener, and the workflow gives you persistence and retries around the whole flow rather than around one HTTP call.

Reach for it when the reaction is an integration: push this change into another system, perhaps in several steps, without hosting any code. The trigger de-duplicates deliveries of one event, not events describing one change — three quick updates to one product are three events and three runs. Key your writes on the entity if that matters.

Integration Studio is experimental and its schemas are drafts (as of 2026-09), so expect a workflow built today to need a migration later. See Event triggers.

Don't use it when you need the event in a system you control with your own retry and ordering logic (a webhook fits), or when the flow is logic that other channels must share (an App fits).

An App handler

An App subscribes by listing topics under events.listens in its manifest, and the platform invokes the App's own function when one fires.

This is verified for two events only: app.installed and app.uninstalled (as of 2026-09). Don't design business reactions — an order placed, a price changed — around an App handler yet, and don't rely on app.installed alone to seed defaults, because it does not reliably fire on a Marketplace install. Events you receive has the details and the workaround.

Choose it when the reaction is App logic and the event is one of the two verified ones. Don't use it for business reactions such as an order placed; use a webhook or a workflow trigger.

If an App needs to announce a change to others, it declares the event in its manifest. The platform fires it on a row change, or the App fires it with db.events.emit(). See Events you emit, and Publish a business event from your App for the worked guide.

Reporting: webhooks, plus the API

The event pages under Analytics are not a separate mechanism. They describe the same Cockpit-registered webhook endpoint from a reporting angle: events are the freshness feed that makes a counter move without polling.

An event feed can't answer for the past and isn't a copy of the entity, so a reporting pipeline needs both feeds. Pull from the API for completeness and backfill; take events for freshness. Pull versus push explains why push alone is the one to avoid.

Where to go next

• Events and Event types — the stream, the envelope, and how topics are named.
• Webhooks — register an endpoint and receive deliveries; Security shows how to verify one and Delivery what happens when your endpoint fails.
• Event triggers — start a workflow from an event.
• Receive platform events at your own endpoint — the guide that acts on this choice for a webhook.
• Hand an order to the ERP — a workflow on the order-placement event, worked through.
• Publish a business event from your App — the guide that acts on this choice for an App that announces a change.
• Choose which system owns each entity — the "out of Revenue Cloud" side of every integration feed.
• Events you receive — what an App handler can rely on (as of 2026-09).
• Getting data out — the reporting paths in full.