# Webhooks from Orbit

> What Orbit's webhooks send, how to check the signature, the order and repeats to expect, how retries work, and every event you can choose.

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

Webhooks set up under **Webhooks** in Orbit send events from every satellite to your endpoint, in one format. Owners and admins add them; see [Send events to your own systems with webhooks](https://docs.bifrostorbit.com/orbit/admins/webhooks/). To connect a no-code tool instead of your own code, follow the guides for [Make](https://docs.bifrostorbit.com/orbit/admins/flows-make/), [Zapier](https://docs.bifrostorbit.com/orbit/admins/flows-zapier/) and [n8n](https://docs.bifrostorbit.com/orbit/admins/flows-n8n/).

## The request

Each event is one `POST` to your address, with a JSON body and these headers:

| Header | What it holds |
| --- | --- |
| `content-type` | `application/json` |
| `x-orbit-event` | The event's type, such as `travel.booking.created` |
| `x-orbit-delivery` | The id of this delivery. A retry of the same delivery keeps it. |
| `x-orbit-timestamp` | When this attempt was sent, in milliseconds since 1970 |
| `x-orbit-signature` | The HMAC-SHA256 of the timestamp, a full stop and the raw body, in lowercase hex |
| `user-agent` | `Bifrost-Orbit-Webhooks/1.0` |

The body is the event exactly as [Orbit Exchange](https://docs.bifrostorbit.com/orbit/developers/orbit-exchange/) describes it, with one extra field, `event`, which repeats `type`:

```json
{
  "event": "travel.booking.created",
  "id": "8b0d3f2e-6a1c-4c55-9a51-0f6ad2d3c901",
  "type": "travel.booking.created",
  "version": 1,
  "time": "2026-11-08T09:14:02.118Z",
  "source": "travel",
  "sequence": 311,
  "tenant": { "organisationId": "6650c0ffee0000000000abcd", "spaceId": null, "environmentKey": null, "regionKey": null, "localeCode": null },
  "subject": { "resourceType": "booking", "id": "6650c0ffee0000000000b00c" },
  "actor": { "type": "system", "id": null },
  "data": { "bookingId": "6650c0ffee0000000000b00c", "reference": "NW-7ERJDH", "tripId": "6650c0ffee0000000000a11a", "departureId": "6650c0ffee0000000000d0d0", "status": "confirmed", "travellers": 2, "total": 249000, "currency": "EUR", "brandId": "6650c0ffee0000000000beef" }
}
```

`event` and `data` are where the SDKs' webhook helpers look, so the same code reads webhooks from Orbit and from CMS Orbit.

## Check the signature

Use the SDK for your language. Each takes the raw body, the two headers and your signing secret, and refuses messages that are more than five minutes old:

```ts
import { verifyWebhook } from "@bifrost-orbit-cms/sdk";

export async function POST(request: Request) {
  const body = await request.text();
  const result = await verifyWebhook({
    body,
    timestamp: request.headers.get("x-orbit-timestamp"),
    signature: request.headers.get("x-orbit-signature"),
    secret: process.env.ORBIT_WEBHOOK_SECRET!,
  });
  if (!result.valid) return new Response("Bad signature", { status: 401 });
  if (result.event === "travel.booking.created") {
    // add the booking to your CRM
  }
  return new Response(null, { status: 204 });
}
```

In PHP use `Webhook::verify`, in Swift `CMSWebhook.verify` and in Kotlin `CmsWebhook.verify`. Without an SDK, follow [Verify webhooks from Bifröst Orbit](https://docs.bifrostorbit.com/orbit/developers/verify-webhooks/): it is the `x-orbit` signature there.

## Answer quickly, expect repeats

- Answer with any `2xx` status within 10 seconds, then do slow work afterwards. Anything else counts as a failure. Redirects are not followed.
- An event can arrive more than once, for example when your answer was lost. Use `id` to ignore an event you have already handled.
- Events can arrive out of order. Each satellite numbers its events in `sequence`, so for one `subject.id`, a lower number is older.

## Retries

A failed delivery is tried again after 1 minute, then 2, 4, 8 and so on, at most 6 hours apart, for up to 24 hours after the first attempt. After that it is marked failed, and you can send it again from **Deliveries** in Orbit.

If every delivery to a webhook fails for 24 hours, Orbit switches it off and emails the owners and admins. It sends nothing more until someone switches it on again.

## Test messages

**Send a test** in Orbit sends this, signed like any other message:

```json
{
  "event": "orbit.webhook.test",
  "type": "orbit.webhook.test",
  "test": true,
  "source": "orbit",
  "data": { "name": "Bookings to our CRM", "message": "A test from Orbit. Your endpoint received and can verify webhooks from Bifröst Orbit." }
}
```

The rest of the envelope is filled in as usual. Answer it like any other event.

## Every event you can choose

The [event reference](https://docs.bifrostorbit.com/reference/events/) lists every field in each event's `data`, built from the same definitions the satellites use. What each event means is on the satellite's own events page.

| Satellite | Events |
| --- | --- |
| Orbit | `orbit.organisation.updated`, `orbit.organisation.deleted`, `orbit.member.added`, `orbit.member.changed`, `orbit.member.removed`. A member event's `data` has `userId`, `email`, `name`, `role`, `previousRole`, `satellites` and `invited` (true when they were invited because they had no account yet). |
| CMS Orbit | `cms.page.published`, `cms.page.unpublished`, `cms.page.rolledBack`, `cms.page.promoted`, `cms.page.trashed`, `cms.page.restored`, `cms.page.purged`, `cms.folder.moved`, `cms.release.published`, `cms.redirect.changed`, `cms.navigation.changed`, `cms.flags.changed`, `cms.experiment.changed`, `cms.taxonomy.changed`, `cms.review.requested`, `cms.review.decided`, `cms.asset.uploaded`. See [CMS Orbit events](https://docs.bifrostorbit.com/cms/developers/events/). |
| Travel Orbit | `travel.trip.published`, `travel.trip.unpublished`, `travel.trip.changed`, `travel.departure.changed`, `travel.departure.full`, `travel.departure.reopened`, `travel.booking.created`, `travel.booking.changed`, `travel.booking.cancelled`, `travel.payment.succeeded`, `travel.payment.failed`, `travel.payment.refunded`. See [Travel Orbit events](https://docs.bifrostorbit.com/travel/developers/webhooks-and-events/). |
| Commerce Orbit | `commerce.product.published`, `commerce.product.unpublished`, `commerce.product.changed`, `commerce.stock.changed`, `commerce.collection.changed`, `commerce.order.placed`, `commerce.order.paid`, `commerce.order.fulfilled`, `commerce.order.refunded`, `commerce.order.cancelled`, `commerce.order.edited`, `commerce.return.requested`, `commerce.return.approved`, `commerce.return.rejected`, `commerce.return.received`, `commerce.mam.status`. See [Commerce Orbit events](https://docs.bifrostorbit.com/commerce/developers/webhooks-and-events/). |
| Presence Orbit | `presence.review.received`, `presence.review.replied`, `presence.feedback.received`, `presence.request.sent`. See [Presence Orbit events](https://docs.bifrostorbit.com/presence/developers/events/). |
| Booking Orbit | `booking.appointment.booked`, `booking.appointment.rescheduled`, `booking.appointment.cancelled`, `booking.appointment.completed`, `booking.appointment.noShow`. See [Booking Orbit events](https://docs.bifrostorbit.com/booking/developers/events/). |
| Careers Orbit | `careers.job.published`, `careers.job.updated`, `careers.job.closed`, `careers.application.created`, `careers.application.stageChanged`, `careers.application.rejected`, `careers.application.withdrawn`, `careers.application.hired`, `careers.review.requested`, `careers.candidate.erased`, `careers.posting.statusChanged`, `careers.campaign.sent`, `careers.referral.created`, `careers.assessment.completed`, `careers.offer.sent`, `careers.offer.accepted`, `careers.offer.declined`. See [Careers Orbit events](https://docs.bifrostorbit.com/careers/developers/webhooks-and-events/). |
| Insights Orbit | `insights.site.created`, `insights.site.trashed`, `insights.site.restored`, `insights.site.purged`, and `insights.goal.reached` for goals marked **Use in flows and webhooks**, once per visit |

Choosing **Everything from** a satellite also sends events it adds later.
