# Notifications

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 of the:

1. **Product**
2. **Availability**
3. **Booking**

## Managing Notification Subscriptions

You can subscribe to notifications by creating subscriptions, which can be [created](#create-notification), [updated](#update-notification) or [deleted](#delete-notification). You can also [list](#list-notifications) your subscriptions or [retrieve](#get-notification) a specific one.

### Create Subscription

<mark style="color:green;">`POST`</mark> `/notifications/subcriptions`

**Headers**

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

**Body**

<table><thead><tr><th width="246">Name</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>The URL where you want the  notifications to be sent to</td></tr><tr><td><code>notificationTypes</code></td><td>array</td><td><p>The type(s) of notifications you would like to be subscribed to as a part of this subscription. Possible events are:</p><ol><li><code>PRODUCT_UPDATE</code> (changes to product object, including option, ticket, etc. within it)</li><li><code>AVAILABILITY_UPDATE</code> (changes to availabilities)</li><li><code>BOOKING_UPDATE</code> (changes to bookings)</li></ol></td></tr><tr><td><code>headers</code></td><td>object</td><td>List of HTTP headers you want to be included in the request (eg. for authentication)</td></tr></tbody></table>

#### Example Request

```json
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**

```json
{
  "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.&#x20;

### Update Subscription

Update an existing notification:

<mark style="color:yellow;">`PATCH`</mark> `/notifications/subscriptions/<id>`

### Delete Subscription

Delete an existing notification:

<mark style="color:red;">`DELETE`</mark> `/notifications/subscriptions/<id>`

### Get Subscription

Retrieve an existing notification:&#x20;

<mark style="color:blue;">`GET`</mark> `/notifications/subscriptions/<id>`

### List Subscriptions&#x20;

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

<mark style="color:blue;">`GET`</mark> `/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](https://docs.octo.travel/octo-api-core/products#products-id), [Get Booking](https://docs.octo.travel/octo-api-core/bookings#bookings-uuid), and [Availability](https://docs.octo.travel/octo-api-core/availability#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:

```json
{
  "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`:

{% tabs %}
{% tab title="PRODUCT\_UPDATE" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "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"
  }
}
</code></pre>

`productId` then be used to request the updated product details using [Get Product](https://docs.octo.travel/octo-api-core/products#get-product).
{% endtab %}

{% tab title="AVAILABILITY\_UPDATE" %}

```json
{
  "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](https://docs.octo.travel/octo-api-core/availability) endpoints.&#x20;
{% endtab %}

{% tab title="BOOKING\_UPDATE" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "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"
  }
}
</code></pre>

Booking `uuid` then be used to request the updated product details using [Get Booking](https://docs.octo.travel/octo-api-core/bookings#bookings-uuid).
{% endtab %}
{% endtabs %}

{% hint style="info" %}
It is recommended that all notifications receive a 2xx response to confirm successful delivery and processing.
{% endhint %}