Notifications

Notifications on changes to product, availability or booking

This new proposed capability is currently undergoing Specification Committee and Member reviews. Become a member to contribute to capability development.

To use this capability add notifications to your Octo-Capabilities header. This capability allows you to subscribe to be notified when something changes against either the:

1. Product

2. Availability

3. Booking

Managing Notification Subscriptions

You can subscribe to notifications by creating subscriptions, which can be created, updated or deleted. You can also list your subscriptions or retrieve a specific one.

Create Subscription

POST /notifications/subcriptions

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>
Octo-Capabilities	notifications

Body

Name	Type	Description
url	string	The URL where you want the notifications to be sent to
notificationTypes	array	The type(s) of notifications you would like to be subscribed to as a part of this subscription. Possible events are: PRODUCT_UPDATE (changes to product object, including option, ticket, etc. within it) AVAILABILITY_UPDATE (changes to availabilities) BOOKING_UPDATE (changes to bookings)
headers	object	List of HTTP headers you want to be included in the request (eg. for authentication)

Example Request

POST /notifications/subcriptions
Content-Type: application/json

{
  "url": "https://example.com/myapp/example1",
  "notificationTypes": [
    "PRODUCT_UPDATE",
    "AVAILABILITY_UPDATE",
    "BOOKING_UPDATE"
  ],
  "headers": {
    "Api-Key": "secret"
  }
}

Example Response

{
  "id": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "notificationTypes": [
    "PRODUCT_UPDATE",
    "AVAILABILITY_UPDATE",
    "BOOKING_UPDATE"
  ],
  "url": "https://example.com/myapp/example1",
  "headers": {
    "Api-Key": "secret"
  }
}

Note the id of your created subscription. You can use it to manage your created notification as described below. The REST endpoints will behave as you'd expect using the same schema as above.

Update Subscription

Update an existing notification:

PATCH /notifications/subscriptions/<id>

Delete Subscription

Delete an existing notification:

DELETE /notifications/subscriptions/<id>

Get Subscription

Retrieve an existing notification:

GET /notifications/subscriptions/<id>

List Subscriptions

List all of the notifications associated with your account (Bearer Token):

GET /notifications/subscriptions

Receiving Notifications

When receiving notification you've created, the request body will not include the fully serialized object of either a product, availability or booking. Instead it'll simply provide you with the parameters needed to fetch that updated resource if you choose to. This can be done using OCTO Core Get Product, Get Booking, and Availability endpoints correspondingly. This is to reduce the volume of data sent in the request and allow the receiver of the notification to chose which capabilities they want to include when fetching the updated resource. All notifications will be HTTP POST requests and include a standard payload scheme:

{
  "subscriptionId": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "notificationType": "PRODUCT_UPDATE",
  "data": {
    ...
  }
}

The value included in data is the content of the notification will vary based on type:

PRODUCT_UPDATE

{
  "id": "503eac5-bfab-4465-aad1-fc023b23cdc6",
  "subscriptionId": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "notificationType": "PRODUCT_UPDATE",
  "utcCreatedAt": "2024-05-07T15:47:32Z",

  "data": {
    "productId": "ff53a321-a07b-4428-b8b3-086c94fb4147"
  }
}

productId then be used to request the updated product details using Get Product.

AVAILABILITY_UPDATE

{
  "id": "5d6e16a3-17af-4293-b3a5-406b5be5fc37",
  "subscriptionId": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "notificationType": "AVAILABILITY_UPDATE",
  "utcCreatedAt": "2024-05-07T15:42:37Z",
  
  "data": {
    "productId": "ff53a321-a07b-4428-b8b3-086c94fb4147",
    "optionId": "49bb9bd7-2cb2-4125-9e8b-c6efdee1e060",
    "localDateStart": "2025-01-01",
    "localDateEnd": "2025-01-07"
  }
}

The data object will contain request parameters compatible with any valid Availability Check request, eg. including availabilityIds instead of localDateStart/localDateEnd.

You can then retrieve change details for these using Availability endpoints.

BOOKING_UPDATE

{
  "id": "2a84129e-3fab-461d-adb1-b12217ef0637",
  "subscriptionId": "5c7d6dbb-cd4c-48fd-9709-0ebaa14d7a00",
  "notificationType": "BOOKING_UPDATE",
  "utcCreatedAt": "2024-05-07T15:49:31Z",

  "data": {
    "uuid": "383ef506-f632-4cc1-bdf1-f619e12e94dd"
  }
}

Booking uuid then be used to request the updated product details using Get Booking.

It is recommended that all notifications receive a 2xx response to confirm successful delivery and processing.