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.
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.
For added security, our webhook supports 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.
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. |
Only order items for standard activity products trigger webhook notifications. Gift products and other special product types do not trigger webhooks.
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. |
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.
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:
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:
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"
}'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.
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}.
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:
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}'