> For the complete documentation index, see [llms.txt](https://docs.bookspot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bookspot.io/capabilities/notifications.md).

# Notifications

{% hint style="info" %}
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`).
{% endhint %}

## 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 reserved (on-hold), confirmed, cancelled, or updated by an admin | `{ "uuid": "booking-uuid", "id": "42", "utcCreatedAt": "2026-04-20T12:34:56Z" }`      |
| `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)

{% stepper %}
{% step %}

### Create Subscription

Request:

{% code title="POST /octo/v1/notifications/subscriptions" %}

```http
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"]
}
```

{% endcode %}

Response:

{% code title="201 Created - Subscription" %}

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

{% endcode %}
{% endstep %}

{% step %}

### List Subscriptions

Request:

{% code title="GET /octo/v1/notifications/subscriptions" %}

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

{% endcode %}

Response:

{% code title="200 OK - Subscriptions List" %}

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

{% endcode %}
{% endstep %}

{% step %}

### Get Subscription

Request:

{% code title="GET /octo/v1/notifications/subscriptions/{id}" %}

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

{% endcode %}
{% endstep %}

{% step %}

### Update Subscription

Request:

{% code title="PATCH /octo/v1/notifications/subscriptions/{id}" %}

```http
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"]
}
```

{% endcode %}
{% endstep %}

{% step %}

### Delete Subscription

Request:

{% code title="DELETE /octo/v1/notifications/subscriptions/{id}" %}

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

{% endcode %}

On success: returns `204 No Content`.
{% endstep %}
{% endstepper %}

### Custom Headers

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

{% code title="Example: headers in subscription body" %}

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

{% endcode %}

### Webhook Payload Format

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

{% code title="Webhook POST payload" %}

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

{% endcode %}

### 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.