Skip to content

Orbit Exchange

The event envelope every satellite uses, how each satellite delivers its events to Orbit Exchange, how often it retries, and what order events arrive in.

Reference6 min read

Orbit Exchange is the hub between the satellites. When something changes, such as a page going live in CMS Orbit or an order being paid in Commerce Orbit, the satellite records an event and sends it to Orbit Exchange. Other satellites use it there: CMS Orbit refreshes the pages that show a product, Insights Orbit counts an order as a goal, and Orbit shows every event on its Exchange page.

You can't read from Orbit Exchange with a key of yours. To receive events, set up a webhook under Webhooks in Orbit: it sends the events you choose from every satellite, in the shape below. See Webhooks from Orbit. Some satellites also have webhooks of their own:

CMS Orbit
Webhooks to your systems
Short signed messages for websites, so they can refresh pages. See Refresh the website when content changes.
Careers Orbit
Webhooks to your systems
The full event, signed, for the events you choose. See Webhooks and events.
Commerce Orbit
Webhooks to your systems
The event's data, signed, for the events you choose. See Webhooks to your own systems.
Travel, Booking, Presence and Insights Orbit
Webhooks to your systems
None of their own. Use webhooks in Orbit.

This page is for understanding what those webhooks are built on, and for reading the events each satellite's docs list.

The envelope

Every event has the same outer shape, whichever satellite sends it. Only data differs.

id
Type
string (UUID)
What it holds
A unique id for this event. Use it to spot repeats.
type
Type
string
What it holds
The event name: the satellite, the thing and what happened, such as commerce.order.paid or careers.application.hired.
version
Type
integer
What it holds
The version of this event's data shape. It goes up only for a change that could break a receiver. Every event is version 1 today.
time
Type
string (ISO 8601, UTC)
What it holds
When it happened.
source
Type
string
What it holds
The satellite that sent it: cms, careers, commerce, travel, booking, presence, insights or orbit.
sequence
Type
integer
What it holds
A number that goes up with each event the satellite sends. See Order below.
tenant.organisationId
Type
string
What it holds
The organisation it happened in.
tenant.spaceId, tenant.environmentKey, tenant.regionKey, tenant.localeCode
Type
string or null
What it holds
Where in CMS Orbit it happened. null for every other satellite.
subject.resourceType
Type
string
What it holds
What changed, such as cms.page, order or application.
subject.id
Type
string
What it holds
The id of what changed.
actor.type
Type
string
What it holds
Who did it: user, apiKey, agent, system or service.
actor.id
Type
string or null
What it holds
Their id, or null for system.
data
Type
object
What it holds
The details. Each satellite's events page lists them.

For example, when Northwilds' Bergen shop is paid for an order:

JSON
{  "id": "1f6c6a52-4f7e-4a63-9c39-5d8b2b6c0c11",  "type": "commerce.order.paid",  "version": 1,  "time": "2026-11-02T09:14:02.118Z",  "source": "commerce",  "sequence": 1042,  "tenant": { "organisationId": "6650c0ffee0000000000abcd", "spaceId": null, "environmentKey": null, "regionKey": null, "localeCode": null },  "subject": { "resourceType": "order", "id": "6650c0ffee0000000000f00d" },  "actor": { "type": "system", "id": null },  "data": { "orderId": "6650c0ffee0000000000f00d", "reference": "NW1042", "status": "open", "paymentStatus": "paid", "fulfilment": "unfulfilled", "total": 46700, "currency": "EUR", "lines": 3, "source": "https://northwilds.com", "shopId": "6650c0ffee0000000000beef" }}

Each satellite's events are listed in its docs: CMS Orbit, Careers Orbit, Commerce Orbit and Travel Orbit.

Delivery

Delivery is at least once. A satellite saves each event before it sends it, and keeps it until Orbit Exchange accepts it. It tries straight away; if Orbit Exchange can't be reached, it tries again later, as below. Because a try can succeed even when the answer is lost, the same event can arrive twice.

The satellites don't all retry on the same schedule:

CMS Orbit
After a failed try, it waits
30 seconds, then twice as long each time
Longest wait
1 hour
Tries in all
12, over about five hours
Then
The event is set aside and counted as failed
Careers, Commerce, Travel, Booking and Presence Orbit
After a failed try, it waits
2 minutes, then twice as long each time
Longest wait
12 hours
Tries in all
12, over about 41 hours
Then
The event is no longer sent
Insights Orbit
After a failed try, it waits
2 seconds, then twice as long each time
Longest wait
About 8.5 minutes
Tries in all
10, over about 17 minutes
Then
The event is set aside and counted as failed

Insights Orbit picks up its retries every second; the others every minute, so their waits can be up to a minute longer than the table says.

Orbit Exchange then takes each event in. It ignores an event whose id it already has, so repeats from a satellite do no harm there. If it can't process an event, it tries again after 2, 4, 8 and 16 seconds, five tries in all, and then sets the event aside. Orbit's Exchange page counts these under Gave up after retries.

Webhooks to your own systems have their own retries, separate from the ones above. Each satellite's webhooks page describes them, and Verify webhooks from Bifröst Orbit compares them.

Order

Each satellite sends its events in the order the changes happen. Orbit Exchange processes the events from one satellite in the order they arrived, and holds back the later ones while an earlier one is being retried. A retried event can still arrive after newer ones, for example when the satellite couldn't reach Orbit Exchange for a while.

sequence puts events back in order. It counts differently in each satellite:

CMS Orbit
sequence counts
Every event CMS Orbit sends, for all organisations together
Commerce Orbit
sequence counts
Every event from one shop
Careers, Travel, Booking and Presence Orbit
sequence counts
Every event from one organisation
Insights Orbit
sequence counts
Every event Insights Orbit sends, for all organisations together

So gaps between your events are normal, and only the order means anything. Compare sequence only between events with the same source, and in Commerce Orbit the same shop. Orbit Exchange itself keeps, for each thing, the event with the highest sequence and ignores older ones that arrive late.

Build receivers that can take repeats

  • Keep the id of events you have handled, and skip any you have seen. Commerce and Careers webhooks also send a delivery id header for the same purpose.
  • Treat an event as a sign that something changed, not as the final state. If order matters, fetch the current state from the satellite's API.
  • Answer quickly and do slow work afterwards.

Was this page helpful?

Read next