# Webhooks To use this capability, add `octo/webhooks` to your `Octo-Capabilities` header. All paths below are shown under `/octo`. This capability lets you configure outbound HTTP webhooks for: * `order_update` * `booking_update` * `availability_update` * `product_update` ## Webhook Object All webhook CRUD endpoints return the same object shape. `capabilities` come from the `Octo-Capabilities` header on create/update requests, not from request body fields. For `order_update`, `octo/cart` is always included automatically. {% openapi src="" path="/webhooks" method="post" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} Create a webhook. {% openapi src="" path="/webhooks/{webhookId}" method="patch" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} Update an existing webhook. Same fields as Create Webhook, but all are optional. `capabilities` are recalculated from the request `Octo-Capabilities` header every time you update. {% openapi src="" path="/webhooks" method="get" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} List webhooks for the authenticated connection. {% openapi src="" path="/webhooks/{webhookId}" method="delete" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} {% openapi src="" path="/webhooks" method="delete" %} [openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media) {% endopenapi %} Provide `url` as a query parameter or request body field. ## Outbound Delivery Payloads When a webhook is delivered to your URL, the HTTP method is always `POST`. ### `webhook` Fields `webhook` is the same `Webhook Object` shown above. ### `supplier` Fields If additional capabilities are active on the webhook, `supplier` may include more fields added by those capabilities. ### `diff[]` Fields `diff` is emitted for `order_update`, `booking_update`, and `product_update`. ### Event Object Serialization The event object payloads use the same serializer methods as the corresponding API endpoints, with the webhook's stored capabilities activated first: * `order` uses the same serialized shape as `GET /orders/:orderId`. * `booking` uses the same serialized shape as `GET /bookings/:uuid`. * `product` uses the same serialized shape as `GET /products/:productId`. * `availability` uses one serialized item from `GET /availability`. This means capability-specific fields (for example content/pricing/extras/questions fields) are included in webhook payloads the same way they appear in those endpoint responses. When `octo/cardPayments` is active, webhook delivery serialization suppresses card payment session payload generation, so detailed `cardPayment` payloads are not emitted. ## Schema Additions (JSON) These are additive fragments showing only fields introduced by this capability. ### `Webhook` ```json { "// ...rest of webhook object": "...", "id": "webhook_booking_update", "event": "booking.updated", "url": "https://www.city-sightseeing.com", "capabilities": [ "octo/pricing", "octo/offers" ], "useContactLanguage": true, "headers": { "X-Webhook-Secret": "whsec_123456abcdef" }, "retryOnError": true } ``` ### `WebhookDeleteByUrlRequest` ```json { "// ...rest of webhook delete by url request object": "...", "url": "https://hooks.example-partner.com/octo/webhook" } ``` ### `WebhookDiffOperation` ```json { "// ...rest of webhook diff operation object": "...", "op": "add", "path": "path-example", "was": "was-example", "value": "value-example" } ``` ### `WebhookEventPayload` ```json { "// ...rest of webhook event payload object": "...", "event": "booking.updated", "webhook": { "id": "webhook_booking_update", "event": "booking.updated", "url": "https://www.city-sightseeing.com" }, "supplier": { "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7", "name": "City Sightseeing Group", "reference": "CITY_SIGHTSEEING_GROUP", "website": "https://www.city-sightseeing.com" }, "order": { "orderId": "ord_20260514_9f3c21", "status": "ON_HOLD", "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b", "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7" }, "booking": { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "status": "ON_HOLD", "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b", "id": "89fe0192-ddcd-430a-b285-e1396a4725d2" }, "product": { "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681", "internalName": "Walking Tour of Barcelona", "reference": "BRC-WALK", "tags": [ "vip", "partner" ] }, "availability": { "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b", "localDateTimeStart": "2026-03-01T09:00:00-08:00", "localDateTimeEnd": "2026-03-01T12:00:00-08:00", "allDay": false, "available": true, "status": "AVAILABLE", "statusMessage": "Limited availability for this departure.", "utcCutoffAt": "2026-05-14T13:00:00Z", "openingHours": [ { "from": "09:00", "to": "17:00" } ] }, "diff": [ { "op": "add", "path": "path-example", "was": "was-example", "value": "value-example" } ] } ``` ### `WebhookRequest` ```json { "// ...rest of webhook request object": "...", "event": "booking.updated", "url": "https://hooks.example-partner.com/octo/webhook" } ```