Notifications

Enable webhook notifications by adding notifications to the Octo-Capabilities header.

Notifications allow you to receive real-time updates when bookings, products, or availability change, instead of polling the API.

Note: All capabilities support both short format (notifications) and prefixed format (octo/notifications).

Notifications Capability

Token Abilities

Your API token must have the appropriate abilities to use notifications:

Ability	Description
octo:read.notifications	List and view notification subscriptions
octo:write.notifications	Create, update, and delete subscriptions

Notification Types

Type	Description	Payload
BOOKING_UPDATE	Triggered when a booking is confirmed or cancelled	{ "uuid": "booking-uuid" }
PRODUCT_UPDATE	Triggered when a product is created, updated, or deleted	{ "productId": "42" }
AVAILABILITY_UPDATE	Triggered when availability changes (schedules, closeouts)	{ "productId": "42", "localDateStart": "2025-01-15", "localDateEnd": "2025-01-20" }

Subscriptions (Create / Read / Update / Delete)

1

Create Subscription

Request:

POST /octo/v1/notifications/subscriptions

POST /octo/v1/notifications/subscriptions
Authorization: Bearer your-api-token
Octo-Capabilities: notifications
Content-Type: application/json

{
  "url": "https://example.com/octo/webhook",
  "notificationTypes": ["BOOKING_UPDATE", "PRODUCT_UPDATE"]
}

Response:

201 Created - Subscription

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/octo/webhook",
  "notificationTypes": ["BOOKING_UPDATE", "PRODUCT_UPDATE"]
}

2

List Subscriptions

Request:

GET /octo/v1/notifications/subscriptions

GET /octo/v1/notifications/subscriptions
Authorization: Bearer your-api-token
Octo-Capabilities: notifications

Response:

200 OK - Subscriptions List

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/octo/webhook",
    "notificationTypes": ["BOOKING_UPDATE", "PRODUCT_UPDATE"]
  }
]

3

Get Subscription

Request:

GET /octo/v1/notifications/subscriptions/{id}

GET /octo/v1/notifications/subscriptions/{id}
Authorization: Bearer your-api-token
Octo-Capabilities: notifications

4

Update Subscription

Request:

PATCH /octo/v1/notifications/subscriptions/{id}

PATCH /octo/v1/notifications/subscriptions/{id}
Authorization: Bearer your-api-token
Octo-Capabilities: notifications
Content-Type: application/json

{
  "url": "https://example.com/new-webhook",
  "notificationTypes": ["BOOKING_UPDATE", "AVAILABILITY_UPDATE"]
}

5

Delete Subscription

Request:

DELETE /octo/v1/notifications/subscriptions/{id}

DELETE /octo/v1/notifications/subscriptions/{id}
Authorization: Bearer your-api-token
Octo-Capabilities: notifications

On success: returns 204 No Content.

Custom Headers

You can include custom headers for authentication with your webhook endpoint by adding a headers object when creating or updating a subscription:

Example: headers in subscription body

{
  "url": "https://example.com/octo/webhook",
  "notificationTypes": ["BOOKING_UPDATE"],
  "headers": {
    "X-Api-Key": "your-secret-key",
    "X-Custom-Header": "custom-value"
  }
}

Webhook Payload Format

When an event occurs, a POST request is sent to your webhook URL:

Webhook POST payload

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "notificationType": "BOOKING_UPDATE",
  "data": {
    "uuid": "booking-uuid-here"
  }
}

Webhook Delivery

• Webhooks are delivered via POST with JSON payload.

• Failed deliveries are retried with exponential backoff.

• Custom headers (if configured) are included with each request.

• BOOKING_UPDATE notifications are only sent to the token that created the booking.