# Use Orbit Flows with n8n

> Start an n8n workflow from anything that happens in your satellites, with a webhook or a flow step, check the signature with the Crypto node and use the event in the next nodes, in n8n Cloud or on your own server.

Source: https://docs.bifrostorbit.com/orbit/admins/flows-n8n/

n8n runs workflows: a trigger node, then nodes that act. It works in n8n Cloud or on your own server. With Orbit Flows and webhooks, the trigger can be anything that happens in your satellites. For example, Northwilds runs n8n on its own server and sends it every paid booking and every Commerce Orbit order, to update stock and its CRM.

You need an owner or admin role in your organisation, a paid satellite plan (see [Who can use webhooks](https://docs.bifrostorbit.com/orbit/admins/webhooks/)) and n8n reachable from the internet over `https://`. Addresses on private or internal networks are refused, so a self-hosted n8n needs a public address.

## Choose how to send

- **A webhook in Orbit**, under **Webhooks**, sends every event you tick, signed. Use it when n8n should decide what happens.
- **Send to a webhook** in a flow sends only when the flow's conditions are true, after an approval or an AI step if you add one. It is not signed.

[Use Orbit Flows with Make](https://docs.bifrostorbit.com/orbit/admins/flows-make/) compares the two in a table.

## 1. Add a Webhook node

1. In n8n, create a workflow and add the **Webhook** trigger node.
2. Set **HTTP Method** to `POST` and give it a **Path**, such as `orbit-orders`.
3. Leave **Respond** on **Immediately**, so Orbit gets an answer at once.

The node has two addresses. The **Test URL** works while you choose **Listen for test event**. The **Production URL**, such as `https://n8n.northwilds.com/webhook/orbit-orders`, works once the workflow is active. Use the test address while you build, then change to the production one.

## 2. Send events to n8n

### With a webhook

1. In Orbit, open **Organisations**, choose your organisation, then **Webhooks**, and choose **Add webhook**.
2. Name it, such as Orders to n8n, and paste the n8n address into **Address**.
3. Tick the events, such as **Everything from** Commerce Orbit, and choose **Add webhook**.
4. Copy the **signing secret** Orbit shows once.
5. In n8n choose **Listen for test event**, then in Orbit choose **⋯** next to the webhook, then **Send a test**.

### Or from a flow

1. In Orbit, open **Flows**, open a flow and choose **Add a step**, then **Send to a webhook**.
2. Paste the n8n address and choose **JSON for your own system**.
3. Write a message and choose **Save flow**.

## 3. Use the fields

The Webhook node puts the message under `body` and the headers under `headers`:

- From a webhook in Orbit: `{{ $json.body.event }}` is the event's type, and `{{ $json.body.data.reference }}` the order or booking reference.
- From a flow step: `{{ $json.body.event.data.reference }}`, your message in `{{ $json.body.message }}`, and an AI step's text in `{{ $json.body.steps.draft001.text }}`.

Add a **Switch** node on `{{ $json.body.event }}` to send each kind of event its own way, such as `commerce.order.paid` to the stock update and `commerce.order.refunded` to accounting. Every field each event has is in the [event reference](https://docs.bifrostorbit.com/reference/events/).

## 4. Check the signature

1. After the Webhook node, add a **Crypto** node. Set **Action** to **Hmac**, **Type** to **SHA256** and **Encoding** to **HEX**, put your signing secret in **Secret**, and set **Value** to:

   `{{ $json.headers["x-orbit-timestamp"] }}.{{ JSON.stringify($json.body) }}`

2. Add an **If** node that goes on only when the Crypto node's result equals `{{ $json.headers["x-orbit-signature"] }}`.

Orbit writes the body as compact JSON, so `JSON.stringify` gives back exactly the text that was signed. Flow steps are not signed, so treat their address like a password.

## 5. Activate the workflow

Switch the workflow to **Active** and make sure Orbit uses the **Production URL**. n8n answers at once, so Orbit counts each message as delivered. If n8n is down, Orbit tries again for up to 24 hours; see [When your system is down](https://docs.bifrostorbit.com/orbit/admins/webhooks/).
