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:
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.
idtypecommerce.order.paid or careers.application.hired.versiondata shape. It goes up only for a change that could break a receiver. Every event is version 1 today.timesourcecms, careers, commerce, travel, booking, presence, insights or orbit.sequencetenant.organisationIdtenant.spaceId, tenant.environmentKey, tenant.regionKey, tenant.localeCodenull for every other satellite.subject.resourceTypecms.page, order or application.subject.idactor.typeuser, apiKey, agent, system or service.actor.idnull for system.dataFor example, when Northwilds' Bergen shop is paid for an order:
{ "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:
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:
sequence countssequence countssequence countssequence countsSo 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
idof 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?