# Order item webhook

To receive live updates for an order item, we can set up a webhook notification for you. When an order item status changes, details are sent directly to the URL you specify via an HTTP `POST` request.

## Setup

To enable webhook notifications, provide the *Strategic partnerships team* with the URL where you want to receive notifications. The URL is configured on your OAuth client and applies to all orders created through it.

## Authentication

For added security, our webhook supports [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide us with a username and password of your choosing and the webhook will include them in the `Authorization` header of the request.

If this option is not possible for you, we can provide a list of our IP addresses so that you can set up a whitelist for your endpoint.

## Triggering statuses

A webhook notification is sent when an order item transitions to one of the following public statuses:

| Public status | Description |
|  --- | --- |
| `OK` | The order item has been confirmed. |
| `PENDING` | The order item is awaiting confirmation (includes needs-confirm, waiting-confirm, and pre-order states). |
| `KO` | There was an issue with the order item (booking error or confirmation refused). |
| `REFUNDED` | The order item has been fully or partially refunded. |
| `CANCELLATION_ERROR` | An error occurred while processing a cancellation. |


Not all status changes trigger a webhook
Only order items for standard activity products trigger webhook notifications. Gift products and other special product types do not trigger webhooks.

## Payload

The webhook sends a JSON payload with the following fields:

| Field | Type | Description |
|  --- | --- | --- |
| `order_id` | string | The internal order ID. |
| `order_uuid` | string | The order UUID. Use this value for subsequent API calls. |
| `order_created` | string | The order creation timestamp in ISO 8601 format. |
| `order_updated` | string | The order's last update timestamp in ISO 8601 format. |
| `order_version` | string | The order version number. Increments with each update. |
| `order_item_uuid` | string | The order item UUID. |
| `order_item_status` | string | The order item's current public status (e.g., `OK`, `PENDING`, `KO`, `REFUNDED`, `CANCELLATION_ERROR`). |
| `order_item_created` | string | The order item creation timestamp in ISO 8601 format. |
| `order_item_updated` | string | The order item's last update timestamp in ISO 8601 format. |
| `order_item_version` | string | The order item version number. Increments with each update. |


## Response

The body of the response is ignored. A 200 status code response confirms the request has been received and will be processed. All other status codes are treated as a failed attempt - another webhook request will be sent later.

## Example

Let's look at an example with our imaginary partner, *Acme*.

They've set up a URL for our webhook at `https://www.acme-partner.com/api/v1/items/musement/webhook`. They've added additional authentication:

* **Username**: JohnSmith
* **Password**: Swordfish


Before submitting the request, the username and password must be base-64 encoded first: `Sm9oblNtaXRoOlN3b3JkZmlzaA==`

The example below shows a typical webhook request when an order item is confirmed:


```bash
curl -X POST 'https://www.acme-partner.com/api/v1/items/musement/webhook' \
-H 'Authorization: Basic <redacted>' \
-H 'Content-Type: application/json' \
--data-raw '{
	"order_id": "13459345",
	"order_uuid": "8e9e5c6e-ea7d-4934-8753-f00954f30d00",
	"order_created": "2018-12-10T13:12:40+0000",
	"order_updated": "2018-12-10T13:12:40+0000",
	"order_version": "16",
	"order_item_uuid": "11045e18-e3ca-42e1-acb4-0d5be75036fd",
	"order_item_status": "OK",
	"order_item_created": "2018-12-10T13:12:40+0000",
	"order_item_updated": "2018-12-10T13:12:40+0000",
	"order_item_version": "22"
}'
```

Here is an example of a webhook request when an order item is refunded:


```bash
curl -X POST 'https://www.acme-partner.com/api/v1/items/musement/webhook' \
-H 'Authorization: Basic <redacted>' \
-H 'Content-Type: application/json' \
--data-raw '{
	"order_id": "13459345",
	"order_uuid": "8e9e5c6e-ea7d-4934-8753-f00954f30d00",
	"order_created": "2018-12-10T13:12:40+0000",
	"order_updated": "2018-12-11T09:30:15+0000",
	"order_version": "18",
	"order_item_uuid": "11045e18-e3ca-42e1-acb4-0d5be75036fd",
	"order_item_status": "REFUNDED",
	"order_item_created": "2018-12-10T13:12:40+0000",
	"order_item_updated": "2018-12-11T09:30:15+0000",
	"order_item_version": "24"
}'
```

## Using the version fields

The `order_version` and `order_item_version` fields increment each time the order or order item is updated. You can use these values to detect out-of-order delivery. If you receive a webhook with a version lower than or equal to one you've already processed, you can safely ignore it.

## Fallback

Webhook delivery is not guaranteed. It is strongly recommended to set up a fallback, allowing your integration to check an order item's status by calling [`GET /orders/{orderUuid}`](/api/booking-flow/order/status).

### Manual trigger

If you have set up a webhook, you can also trigger a notification manually. This is useful if you detect a missed webhook (e.g., via polling) and want to re-process the event through your existing webhook handling logic, rather than building a separate process for polled data.

To trigger a notification manually, make the following request:


```bash
curl -X POST '{baseUrl}/orders/{orderUuid}/items/{orderItemUuid}/notifications' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'
```