> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/webhooks.md).

# Webhooks

Have OrderEazi send your system a message each time something happens, such as an order being dispatched or a document being created.

Asking the API every few minutes whether anything has changed is slow and wastes requests. A webhook works the other way round. Each time a chosen event happens in OrderEazi, such as an order being dispatched, OrderEazi sends the details to your system. The address it sends them to is called an endpoint.

### Before you start

You'll need:

* **An API key:** It needs **Write** on **For Administrative Data**, because you register webhooks through the API. See [Authentication](/central/developers/authentication.md).
* **An endpoint:** This is a web address on your system that accepts a POST request with a JSON body. It answers with a 2xx status code (any success code from 200 to 299).
* **The events you want:** See the [Event catalogue](/central/developers/webhooks/event-catalogue.md).

Someone with the **Webhooks** permission, in the **Integrations** permission group, can also add webhooks in OrderEazi under **Integrations** > **Webhooks**. See [Webhooks](/central/order-management/integrations/webhooks.md).

### How webhooks work

* **An event happens:** For example, a Tax Invoice is created in OrderEazi.
* **A delivery is queued:** OrderEazi queues a delivery for each webhook registered for that event. Each delivery carries a payload (the data about the event).
* **Deliveries are sent:** Once a minute, OrderEazi sends the queued deliveries, one at a time, as POST requests.
* **Your endpoint answers:** A 2xx status code tells OrderEazi it got the delivery. If it doesn't get one, OrderEazi tries again on the next run, up to 3 more times.

Most deliveries arrive within 2 minutes of the event. See [Delivery and troubleshooting](/central/developers/webhooks/delivery-and-troubleshooting.md).

### How to start receiving webhooks

1. Build your endpoint.
2. Register it for an event, with `POST /api/webhook?process=OrderDispatched&url=...`. See [Managing webhooks](/central/developers/webhooks/managing-webhooks.md).
3. Make the event happen in OrderEazi, such as by dispatching a test order.
4. Check that your endpoint receives the delivery within 2 minutes.

**Example:** Your online shop should email customers when their order leaves the warehouse. You register `https://shop.example.com/hooks/oe-7f3k9q2m/dispatched` for `OrderDispatched`. When a trip sheet (the list of deliveries a driver takes out) is dispatched, your shop receives each order's Delivery Note. It matches the Delivery Note to the order by `ProjectNumber`, which OrderEazi returned when the order was created, and emails the customer.

### What each delivery contains

Each delivery is a POST request with a JSON body. The body is the event's payload on its own, with no wrapper. See the [Payload reference](/central/developers/webhooks/payload-reference.md).

| Header                       | What it holds                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `Content-Type`               | `application/json; charset=utf-8`                                                               |
| `X-OE-Webhook-Id`            | The delivery's ID. It stays the same on automatic retries. A delivery you resend gets a new ID. |
| `X-OE-Webhook-Process`       | The event's name, such as `OrderDispatched`.                                                    |
| `X-OE-Webhook-Attempt`       | The attempt number, from 1 to 4.                                                                |
| `X-OE-Webhook-Final-Attempt` | `true` on the last attempt, after which OrderEazi stops trying.                                 |
| `X-OrderEazi-UserId`         | The user ID of the installed app that added the webhook. Only sent for webhooks an app added.   |

### How to protect your endpoint

* **Use HTTPS:** Deliveries hold client and order details.
* **Keep the address private:** Use a path only your system knows, such as `/hooks/oe-7f3k9q2m/dispatched`.
* **Confirm important changes:** Before you release stock or mark an order paid, read the record through the API to get its latest state.

### Related pages

* [Managing webhooks](/central/developers/webhooks/managing-webhooks.md): register and remove webhooks
* [Event catalogue](/central/developers/webhooks/event-catalogue.md): every event you can register for
* [Payload reference](/central/developers/webhooks/payload-reference.md): what each event sends
* [Delivery and troubleshooting](/central/developers/webhooks/delivery-and-troubleshooting.md): retries, resending, and fixing failed deliveries
* [Webhooks](/central/order-management/integrations/webhooks.md) in Order Management: add webhooks and resend deliveries in OrderEazi