Webhooks

Configure webhook endpoints for order, booking, availability, and product updates

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.

Create Webhook

post

Body

application/json

From capability octo/webhooks.

eventstringOptional

Event value.

Example: booking.updated

urlstring · uriOptional

Fully-qualified URL.

Example: https://www.city-sightseeing.com

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

Responses

200

Successful response

application/json

From capability octo/webhooks.

idstringRequired

Webhook identifier.

Example: webhook_booking_update

eventstringRequired

Event value.

Example: booking.updated

urlstring · uriRequired

Fully-qualified URL.

Example: https://www.city-sightseeing.com

capabilitiesstring[]Optional

List of capability values.

Example: ["octo/pricing","octo/offers","octo/waivers"]

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

post

/webhooks

HTTPcURLJavaScriptPython

POST /octo/webhooks HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true
}

200

Successful response

{
  "id": "webhook_booking_update",
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "capabilities": [
    "octo/pricing",
    "octo/offers",
    "octo/waivers"
  ],
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true
}

Create a webhook.

Update Webhook

patch

Path parameters

webhookIdstringRequired

Webhook identifier.

Example: webhook_booking_update

Body

application/json

From capability octo/webhooks.

eventstringOptional

Event value.

Example: booking.updated

urlstring · uriOptional

Fully-qualified URL.

Example: https://www.city-sightseeing.com

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

Responses

200

Successful response

application/json

From capability octo/webhooks.

idstringRequired

Webhook identifier.

Example: webhook_booking_update

eventstringRequired

Event value.

Example: booking.updated

urlstring · uriRequired

Fully-qualified URL.

Example: https://www.city-sightseeing.com

capabilitiesstring[]Optional

List of capability values.

Example: ["octo/pricing","octo/offers","octo/waivers"]

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

patch

/webhooks/{webhookId}

HTTPcURLJavaScriptPython

PATCH /octo/webhooks/{webhookId} HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true
}

200

Successful response

{
  "id": "webhook_booking_update",
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "capabilities": [
    "octo/pricing",
    "octo/offers",
    "octo/waivers"
  ],
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true
}

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.

List Webhooks

get

Responses

200

Successful response

application/json

From capability octo/webhooks.

idstringRequired

Webhook identifier.

Example: webhook_booking_update

eventstringRequired

Event value.

Example: booking.updated

urlstring · uriRequired

Fully-qualified URL.

Example: https://www.city-sightseeing.com

capabilitiesstring[]Optional

List of capability values.

Example: ["octo/pricing","octo/offers","octo/waivers"]

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

get

/webhooks

HTTPcURLJavaScriptPython

GET /octo/webhooks HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

Successful response

[
  {
    "id": "webhook_booking_update",
    "event": "booking.updated",
    "url": "https://www.city-sightseeing.com",
    "capabilities": [
      "octo/pricing",
      "octo/offers",
      "octo/waivers"
    ],
    "useContactLanguage": true,
    "headers": {
      "X-Webhook-Secret": "abc123"
    },
    "retryOnError": true
  }
]

List webhooks for the authenticated connection.

Delete Webhook

delete

Path parameters

webhookIdstringRequired

Webhook identifier.

Example: webhook_booking_update

Body

application/json

From capability octo/webhooks.

urlstring · uriOptional

Fully-qualified URL.

Example: https://www.city-sightseeing.com

eventstringOptional

Event value.

Example: booking.updated

Responses

200

Successful response

application/json

successbooleanRequired

Whether success is enabled.

Example: true

messagestringOptional

Message value.

Example: Deleted successfully.

delete

/webhooks/{webhookId}

HTTPcURLJavaScriptPython

DELETE /octo/webhooks/{webhookId} HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "url": "https://www.city-sightseeing.com",
  "event": "booking.updated"
}

200

Successful response

{
  "success": true,
  "message": "Deleted successfully."
}

Webhook By URL

delete

Body

application/json

From capability octo/webhooks.

urlstring · uriOptional

Fully-qualified URL.

Example: https://www.city-sightseeing.com

eventstringOptional

Event value.

Example: booking.updated

Responses

200

Successful response

application/json

successbooleanRequired

Whether success is enabled.

Example: true

messagestringOptional

Message value.

Example: Deleted successfully.

delete

/webhooks

HTTPcURLJavaScriptPython

DELETE /octo/webhooks HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "url": "https://www.city-sightseeing.com",
  "event": "booking.updated"
}

200

Successful response

{
  "success": true,
  "message": "Deleted successfully."
}

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

{
  "// ...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

{
  "// ...rest of webhook delete by url request object": "...",
  "url": "https://hooks.example-partner.com/octo/webhook"
}

WebhookDiffOperation

{
  "// ...rest of webhook diff operation object": "...",
  "op": "add",
  "path": "path-example",
  "was": "was-example",
  "value": "value-example"
}

WebhookEventPayload

{
  "// ...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

{
  "// ...rest of webhook request object": "...",
  "event": "booking.updated",
  "url": "https://hooks.example-partner.com/octo/webhook"
}