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

From capability octo/webhooks.

eventstringOptional

Event value.

Example: booking.updated

urlstring · uriOptional

Fully-qualified URL.

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

activebooleanOptional

Whether active is enabled.

Example: true

apiKeystringOptional

Api key value.

Example: api_live_ventrata_123456

apiKeysstring[]Optional

List of api key values.

Example: ["api_live_ventrata_123456"]

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

Responses

200

Successful response

application/json

post

/webhooks

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

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

200

Successful response

{
  "webhookId": "webhook_booking_update",
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "active": true,
  "capabilities": [
    "octo/pricing",
    "octo/offers"
  ],
  "apiKey": "api_live_ventrata_123456",
  "apiKeys": [
    "api_live_ventrata_123456"
  ],
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true,
  "secret": "whsec_123456abcdef",
  "createdAt": "2026-05-14T13:00:00Z",
  "updatedAt": "2026-05-14T13:00:00Z"
}

Create a webhook.

Update Webhook

patch

Path parameters

webhookIdstringRequired

Webhook identifier.

Example: webhook_booking_update

Body

From capability octo/webhooks.

eventstringOptional

Event value.

Example: booking.updated

urlstring · uriOptional

Fully-qualified URL.

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

activebooleanOptional

Whether active is enabled.

Example: true

apiKeystringOptional

Api key value.

Example: api_live_ventrata_123456

apiKeysstring[]Optional

List of api key values.

Example: ["api_live_ventrata_123456"]

useContactLanguagebooleanOptional

Whether use contact language is enabled.

Example: true

retryOnErrorbooleanOptional

Whether retry on error is enabled.

Example: true

Responses

200

Successful response

application/json

patch

/webhooks/{webhookId}

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

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

200

Successful response

{
  "webhookId": "webhook_booking_update",
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "active": true,
  "capabilities": [
    "octo/pricing",
    "octo/offers"
  ],
  "apiKey": "api_live_ventrata_123456",
  "apiKeys": [
    "api_live_ventrata_123456"
  ],
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "abc123"
  },
  "retryOnError": true,
  "secret": "whsec_123456abcdef",
  "createdAt": "2026-05-14T13:00:00Z",
  "updatedAt": "2026-05-14T13:00:00Z"
}

Update an existing webhook.

Request Body

Same fields as Create Webhook, but all are optional.

capabilities are recalculated from the request Octo-Capabilities header every time you update.

Response `200`

Returns the updated Webhook Object.

List Webhooks

get

Responses

200

Successful response

application/json

get

/webhooks

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

200

Successful response

[
  {
    "webhookId": "webhook_booking_update",
    "event": "booking.updated",
    "url": "https://www.city-sightseeing.com",
    "active": true,
    "capabilities": [
      "octo/pricing",
      "octo/offers"
    ],
    "apiKey": "api_live_ventrata_123456",
    "apiKeys": [
      "api_live_ventrata_123456"
    ],
    "useContactLanguage": true,
    "headers": {
      "X-Webhook-Secret": "abc123"
    },
    "retryOnError": true,
    "secret": "whsec_123456abcdef",
    "createdAt": "2026-05-14T13:00:00Z",
    "updatedAt": "2026-05-14T13:00:00Z"
  }
]

List webhooks for the authenticated connection.

Response `200`

Array of Webhook Object.

Delete Webhook

delete

Path parameters

webhookIdstringRequired

Webhook identifier.

Example: webhook_booking_update

Body

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

delete

/webhooks/{webhookId}

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

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

delete

/webhooks

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.

Parameters

200 OK with empty body.

Trigger Webhook

post

Path parameters

webhookIdstringRequired

Webhook identifier.

Example: webhook_booking_update

Body

From capability octo/webhooks.

productIdstringOptional

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681

optionIdstringOptional

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b

availabilityIdsstring[]Optional

List of availability identifiers.

Example: ["2026-05-14T09:00:00-04:00","2026-05-15T09:00:00-04:00"]

referencestringOptional

Reference value.

Example: REF-2026-001

emailstringOptional

Email value.

Example: [email protected]

mobilestringOptional

Mobile value.

Example: +12025550123

orderRecordStatestringOptional

Order record state value.

Example: order_record_state-example

productRecordStatestringOptional

Product record state value.

Example: product_record_state-example

Responses

200

Successful response

application/json

post

/webhooks/{webhookId}/trigger

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

{
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
  "availabilityIds": [
    "2026-05-14T09:00:00-04:00",
    "2026-05-15T09:00:00-04:00"
  ],
  "units": [
    {
      "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "quantity": 2,
      "weightValue": 20,
      "weightUnit": "kg"
    }
  ],
  "reference": "REF-2026-001",
  "email": "[email protected]",
  "mobile": "+12025550123",
  "orderRecordState": "order_record_state-example",
  "productRecordState": "product_record_state-example"
}

200

Successful response

{
  "status": "accepted",
  "requestId": "req_20260514_7f29b8",
  "message": "Request accepted for asynchronous processing."
}

Trigger delivery using the webhook's configured event.

Request Body By Event

orderRecordState and productRecordState are optional compressed/base64 record snapshots used to build a JSON Patch diff.

For availability_update, the same filtering/modifier parameters accepted by GET /availability are accepted here.

`availability_update` Nested `units[]` Parameters

For availability_update, one trigger call may produce multiple outbound webhook deliveries (one per serialized availability). Past availabilities are skipped unless historical mode is enabled for the connection.

Trigger Response

Response body is empty.

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, trigger 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": "...",
  "webhookId": "webhook_booking_update",
  "event": "booking.updated",
  "url": "https://www.city-sightseeing.com",
  "active": true,
  "capabilities": [
    "octo/pricing",
    "octo/offers"
  ],
  "apiKey": "api_live_ventrata_123456",
  "apiKeys": [
    "api_live_ventrata_123456"
  ],
  "useContactLanguage": true,
  "headers": {
    "X-Webhook-Secret": "whsec_123456abcdef"
  },
  "retryOnError": true,
  "secret": "whsec_123456abcdef",
  "createdAt": "2026-05-14T13:00:00Z",
  "updatedAt": "2026-05-14T13:00:00Z"
}

`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": {
    "webhookId": "webhook_booking_update",
    "event": "booking.updated",
    "url": "https://www.city-sightseeing.com",
    "active": true
  },
  "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",
  "active": true
}

`WebhookTriggerRequest`

{
  "// ...rest of webhook trigger request object": "...",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b"
}

PreviousPrice Adjustments NextWaitlists

Last updated 9 hours ago

hashtagWebhook Object

hashtagCreate Webhook

hashtagUpdate Webhook

hashtagRequest Body

hashtagResponse 200

hashtagList Webhooks

hashtagResponse 200

hashtagDelete Webhook

hashtagWebhook By URL

hashtagParameters

hashtagTrigger Webhook

hashtagRequest Body By Event

hashtagavailability_update Nested units[] Parameters

hashtagTrigger Response

hashtagOutbound Delivery Payloads

hashtagwebhook Fields

hashtagsupplier Fields

hashtagdiff[] Fields

hashtagEvent Object Serialization

hashtagSchema Additions (JSON)

hashtagWebhook

hashtagWebhookDeleteByUrlRequest

hashtagWebhookDiffOperation

hashtagWebhookEventPayload

hashtagWebhookRequest

hashtagWebhookTriggerRequest

Webhook Object

Create Webhook

Update Webhook

Request Body

Response `200`

List Webhooks

Response `200`

Delete Webhook

Webhook By URL

Parameters

Trigger Webhook

Request Body By Event

`availability_update` Nested `units[]` Parameters

Trigger Response

Outbound Delivery Payloads

`webhook` Fields

`supplier` Fields

`diff[]` Fields

Event Object Serialization

Schema Additions (JSON)

`Webhook`

`WebhookDeleteByUrlRequest`

`WebhookDiffOperation`

`WebhookEventPayload`

`WebhookRequest`

`WebhookTriggerRequest`