# 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.

Source: https://docs.bifrostorbit.com/orbit/developers/orbit-exchange/

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](https://docs.bifrostorbit.com/orbit/developers/orbit-webhooks/). Some satellites also have webhooks of their own:

| Satellite | Webhooks to your systems |
| --- | --- |
| CMS Orbit | Short signed messages for websites, so they can refresh pages. See [Refresh the website when content changes](https://docs.bifrostorbit.com/cms/developers/webhooks/). |
| Careers Orbit | The full event, signed, for the events you choose. See [Webhooks and events](https://docs.bifrostorbit.com/careers/developers/webhooks-and-events/). |
| Commerce Orbit | The event's data, signed, for the events you choose. See [Webhooks to your own systems](https://docs.bifrostorbit.com/commerce/developers/outgoing-webhooks/). |
| Travel, Booking, Presence and Insights Orbit | 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.

| Field | Type | What it holds |
| --- | --- | --- |
| `id` | string (UUID) | A unique id for this event. Use it to spot repeats. |
| `type` | string | The event name: the satellite, the thing and what happened, such as `commerce.order.paid` or `careers.application.hired`. |
| `version` | integer | 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` | string (ISO 8601, UTC) | When it happened. |
| `source` | string | The satellite that sent it: `cms`, `careers`, `commerce`, `travel`, `booking`, `presence`, `insights` or `orbit`. |
| `sequence` | integer | A number that goes up with each event the satellite sends. See Order below. |
| `tenant.organisationId` | string | The organisation it happened in. |
| `tenant.spaceId`, `tenant.environmentKey`, `tenant.regionKey`, `tenant.localeCode` | string or null | Where in CMS Orbit it happened. `null` for every other satellite. |
| `subject.resourceType` | string | What changed, such as `cms.page`, `order` or `application`. |
| `subject.id` | string | The id of what changed. |
| `actor.type` | string | Who did it: `user`, `apiKey`, `agent`, `system` or `service`. |
| `actor.id` | string or null | Their id, or `null` for `system`. |
| `data` | object | 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](https://docs.bifrostorbit.com/cms/developers/events/), [Careers Orbit](https://docs.bifrostorbit.com/careers/developers/webhooks-and-events/), [Commerce Orbit](https://docs.bifrostorbit.com/commerce/developers/webhooks-and-events/) and [Travel Orbit](https://docs.bifrostorbit.com/travel/developers/webhooks-and-events/).

## 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:

| Satellite | After a failed try, it waits | Longest wait | Tries in all | Then |
| --- | --- | --- | --- | --- |
| CMS Orbit | 30 seconds, then twice as long each time | 1 hour | 12, over about five hours | The event is set aside and counted as failed |
| Careers, Commerce, Travel, Booking and Presence Orbit | 2 minutes, then twice as long each time | 12 hours | 12, over about 41 hours | The event is no longer sent |
| Insights Orbit | 2 seconds, then twice as long each time | About 8.5 minutes | 10, over about 17 minutes | 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](https://docs.bifrostorbit.com/orbit/developers/verify-webhooks/) 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:

| Satellite | `sequence` counts |
| --- | --- |
| CMS Orbit | Every event CMS Orbit sends, for all organisations together |
| Commerce Orbit | Every event from one shop |
| Careers, Travel, Booking and Presence Orbit | Every event from one organisation |
| Insights Orbit | 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.
