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

# Webhooks

Receive real-time HTTP notifications when events occur in your Hostel Mate property — new bookings, payments, messages, and more.

Webhooks let you subscribe to events and receive an HTTP `POST` to your server the moment something happens in Hostel Mate — no polling required.

## Managing endpoints

Webhooks are part of the **Advanced** plan (the rest of the API works on every plan except Lite). On other plans the webhook routes below answer `403` with `{"detail": "This feature is only available on the Advanced plan.", "upgrade_required": "True"}`, and a property that leaves the Advanced plan stops receiving events. An account Admin can move to Advanced from [Plan & Billing](https://docs.hostelmate.co/finance-management/plan-billing.md#changing-your-plan).

Webhook endpoints are managed from the **API Access → Webhooks** tab in your Hostel Mate dashboard. From there you can:

* Register a new endpoint (URL + event subscriptions). A new endpoint starts with the three "all channels" booking events ticked; add or remove any others.
* Change which events an endpoint receives (**Edit events**)
* Enable or disable an endpoint without deleting it
* Delete an endpoint and its delivery history
* Inspect the last 50 delivery attempts per endpoint

You can also manage endpoints programmatically via the Client API — see [Webhook API reference](#api-reference) below.

***

## Supported events

An endpoint receives only the events it subscribes to.

Bookings and messages come in two kinds. The `.any.` events cover every channel. The original events (`booking.created`, `booking.updated`, `booking.cancelled`, `message.received`) keep their original, narrower meaning, so an endpoint that already uses them keeps getting exactly what it got before. An endpoint can subscribe to both kinds; it then gets one delivery for each.

| Event                    | Fired when                                                                                                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking.any.created`    | A new booking arrives from any channel: your front desk, your booking page, a connected channel (Booking.com, Hostelworld, Airbnb and others) or the Client API. A waitlisted booking counts as created. |
| `booking.any.updated`    | Anything in a booking changes, on any channel: status (including check-in and no-show), dates, beds, amounts or the booking notes.                                                                       |
| `booking.any.cancelled`  | A booking is cancelled on any channel, or deleted through the Client API.                                                                                                                                |
| `booking.created`        | A booking is made through the Client API.                                                                                                                                                                |
| `booking.updated`        | A booking is changed through the Client API: dates, room, notes or status.                                                                                                                               |
| `booking.cancelled`      | A booking is deleted through the Client API.                                                                                                                                                             |
| `booking.note.added`     | A note is added to a booking.                                                                                                                                                                            |
| `booking.note.updated`   | A booking note changes: edited by your staff, or moved to a new date along with its night.                                                                                                               |
| `booking.note.deleted`   | A booking note is deleted: by your staff, or together with the night it was on.                                                                                                                          |
| `guest.updated`          | A guest's details change: name, email, phone, country, city, nationality, date of birth, language, newsletter or ID document.                                                                            |
| `self_checkin.completed` | A guest finishes online check-in.                                                                                                                                                                        |
| `message.any.received`   | A guest sends a message: email, WhatsApp, Booking.com or Airbnb.                                                                                                                                         |
| `message.received`       | A guest sends a message on Booking.com or Airbnb.                                                                                                                                                        |
| `payment.created`        | A payment is recorded through the Client API.                                                                                                                                                            |
| `payment.updated`        | A payment is changed through the Client API.                                                                                                                                                             |

**Timing.** Most events are sent within seconds. Events caused by Hostel Mate's own scheduled jobs (for example a booking picked up from a channel in the background) can arrive up to about 15 minutes later.

**What doesn't send an event:** bookings brought in by a data import, and payments made outside the Client API. A change to a guest sends `guest.updated`, not a booking event. Saving a note or a guest without changing anything sends nothing.

***

## Payload envelope

Every webhook delivery sends a JSON body in this shape:

```json
{
  "id": "f3c2a1b0-...",
  "type": "booking.created",
  "property_id": "73d9244a-44df-4254-b304-999c122b8dc1",
  "created_at": "2025-04-22T14:30:00Z",
  "data": { ... }
}
```

| Field         | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `id`          | Unique delivery ID (UUID). Use this to deduplicate retries.   |
| `type`        | The event name — same strings as the subscription list above. |
| `property_id` | Your property UUID.                                           |
| `created_at`  | ISO 8601 UTC timestamp of when the event was fired.           |
| `data`        | Event-specific payload (see per-event shapes below).          |

### `booking.any.created` / `booking.any.updated` / `booking.any.cancelled` data

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "reserved",
  "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
  "total": 52000,
  "dates": [
    { "date": "2025-12-19", "amount": 26000 },
    { "date": "2025-12-20", "amount": 26000 }
  ],
  "guest": {
    "id": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "createdAt": "2025-10-01T10:00:00Z",
  "updated": "2025-10-02T11:05:13Z",
  "booking": {
    "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
    "status": "reserved",
    "channel": "Booking",
    "checked_in": false,
    "total": 52000,
    "...": "the rest of the booking"
  }
}
```

The three events send the same data, taken at the moment of the change. It has every key of the original booking events below, with the same values:

| Field                  | Description                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bookingId`, `status`  | The booking's ID and status.                                                                                                                                                                           |
| `room`                 | The room of the first night (`null` when the booking has no bed yet).                                                                                                                                  |
| `total`, `dates`       | The total and each night's amount.                                                                                                                                                                     |
| `guest`                | The booking's guest (empty strings when there is none).                                                                                                                                                |
| `createdAt`, `updated` | The booking's `created` and `updated` times. Despite its name, `created` is refreshed whenever the booking is saved, so it is not always when the booking was made; `updated` is when it last changed. |
| `booking`              | The full booking, exactly as [`GET /client/bookings/{bookingId}`](https://docs.hostelmate.co/api-documentation/bookings/get.md) returns it.                                                            |

Amounts are in **minor units** (integer cents). For a booking deleted through the Client API, the data shows it as it was just before the delete.

### `booking.created` / `booking.updated` / `booking.cancelled` data

These are the same as they have always been.

`booking.created`: the booking as the [create request](https://docs.hostelmate.co/api-documentation/bookings/create.md) returns it.

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "reserved",
  "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
  "total": 52000,
  "dates": [
    { "date": "2025-12-19", "amount": 26000 },
    { "date": "2025-12-20", "amount": 26000 }
  ],
  "guest": {
    "id": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "createdAt": "2025-10-01T10:00:00Z"
}
```

`booking.updated` after a change of dates, room or notes (`PATCH /client/bookings/{bookingId}`): the booking as that request returns it.

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "reserved",
  "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
  "total": 52000,
  "dates": [
    { "date": "2025-12-19", "amount": 26000 },
    { "date": "2025-12-20", "amount": 26000 }
  ],
  "updated": "2025-10-02T11:05:13Z"
}
```

`booking.updated` after a status or notes update (`POST /client/bookings/{bookingId}/update`):

```json
{ "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77", "status": "paid" }
```

`booking.cancelled`:

```json
{ "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77" }
```

### `booking.note.added` / `booking.note.updated` / `booking.note.deleted` data

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "note": {
    "id": "0c5d1e7a-...",
    "date": "2025-12-19",
    "text": "Arrives late, around 23:00",
    "for_housekeeping": false
  },
  "details": {}
}
```

`note.date` is the night the note is for (`null` for a note on the whole stay). `details` says what changed:

| Change                     | `details`                                                                     |
| -------------------------- | ----------------------------------------------------------------------------- |
| Added, or deleted by staff | `{}`                                                                          |
| Edited by staff            | `prev_text`, `prev_date`, `prev_for_housekeeping`: the values before the edit |
| Moved with its night       | `prev_date`, `"reason": "moved_with_booking"`                                 |
| Deleted with its night     | `"reason": "night_deleted"`                                                   |

### `guest.updated` data

```json
{
  "guestId": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
  "changed": ["phone", "address.city"],
  "guest": {
    "guestId": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
    "first_name": "John",
    "phone": "+34600000000",
    "...": "the rest of the guest"
  }
}
```

`guest` is the guest exactly as [`GET /client/guests/{guestId}`](https://docs.hostelmate.co/api-documentation/guests/get.md) returns it. `changed` lists the fields of that record that changed, with nested fields written with a dot, for example `first_name`, `phone`, `country_code`, `address.city`, `address.country_code` or `preferences.language`. `id_document` means the guest's ID document number or type changed; the number itself is never sent.

### `self_checkin.completed` data

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "guestId": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
  "eta": "15:00",
  "hasIdDocument": true
}
```

`eta` is the arrival time the guest typed (`null` if none). `hasIdDocument` is `true` when the guest uploaded an ID.

### `payment.created` data

```json
{
  "paymentId": "uuid",
  "amount": "150.00",
  "paymentMethod": "Cash",
  "type": "income"
}
```

Payment amounts are **decimal strings** (not minor units).

### `payment.updated` data

```json
{
  "paymentId": "uuid",
  "amount": "175.00"
}
```

### `message.any.received` / `message.received` data

```json
{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "messageId": "message-id",
  "threadId": "thread-id",
  "content": "Hi, can I check in early?",
  "channel": "BOOKING_COM",
  "guestName": null
}
```

| Field       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`   | `BOOKING_COM`, `AIRBNB`, `EMAIL` or `WHATSAPP`. `message.received` is only sent for `BOOKING_COM` and `AIRBNB`.                                                                    |
| `content`   | Booking.com and Airbnb: the full message (empty when the message is only attachments). Email and WhatsApp: the first 100 characters; `"New message"` when the message has no text. |
| `bookingId` | The booking the conversation belongs to, or `null` when it isn't linked to one. WhatsApp conversations are kept per guest phone, not per booking, so they are always `null`.       |
| `threadId`  | Booking.com and Airbnb: the conversation ID. Email and WhatsApp: `null`.                                                                                                           |
| `guestName` | Email and WhatsApp: the sender's name (for WhatsApp, the sender's number when no name is known). Booking.com and Airbnb: `null`.                                                   |

***

## Request headers

Each delivery includes these headers on the `POST` request to your endpoint:

| Header           | Value                                    |
| ---------------- | ---------------------------------------- |
| `Content-Type`   | `application/json`                       |
| `X-HM-Signature` | `sha256=<hex digest>`                    |
| `X-HM-Event`     | Event name, e.g. `booking.created`       |
| `X-HM-Delivery`  | Delivery UUID (matches `id` in the body) |

***

## Verifying the signature

Every delivery is signed with HMAC-SHA256 using your endpoint secret. **Always verify the signature** before processing.

The signature covers the raw request body bytes.

```javascript
// Node.js example
const crypto = require('crypto');

function verifySignature(secret, rawBody, signatureHeader) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(rawBody)          // Buffer or string of the raw request body
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signatureHeader)
    );
}
```

```python
# Python example
import hmac, hashlib

def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

Your endpoint must return a **2xx status code** within **5 seconds** for the delivery to be considered successful.

***

## Retries and backoff

Failed deliveries (non-2xx response or timeout) are retried once. Retries go out in rounds every 5 minutes, so the retry is sent at the first round at least 1 minute after the failure:

| Attempt | Sent again after the previous failure  |
| ------- | -------------------------------------- |
| 2       | about 1–6 minutes                      |
| —       | Marked **dead** after 2 total attempts |

Dead deliveries are visible in the dashboard delivery log.

**You can receive the same event more than once.** If your server sends nothing back for 5 seconds, the send counts as failed, even if your server goes on to process the event, so it is sent again. Answer with a 2xx first and do slow work afterwards. The `id` field in the payload (also sent as the `X-HM-Delivery` header) stays the same on every retry: use it to deduplicate.

**Events can arrive out of order**, for example when a retry lands after a newer event. Use the timestamps in the payload, or read the booking again, rather than relying on arrival order.

**Don't redirect your webhook URL.** Point it at the final address. We don't follow redirects: an answer like `301` or `302` counts as a failed delivery and is retried like any other failure.

***

## API reference

All webhook endpoints require `X-API-Key` authentication. `POST` and `PATCH` require an `Idempotency-Key` header.

### List endpoints

```
GET /client/webhooks
```

Returns all webhook endpoints for your property.

```json
[
  {
    "id": "uuid",
    "url": "https://example.com/webhook",
    "events": ["booking.created", "payment.created"],
    "is_active": true,
    "created_at": "2025-04-22T10:00:00Z",
    "updated_at": "2025-04-22T10:00:00Z"
  }
]
```

### Create endpoint

```
POST /client/webhooks
```

```json
{
  "url": "https://example.com/webhook",
  "events": ["booking.created", "booking.cancelled", "payment.created"]
}
```

The `url` must start with `https://` and point to a public internet address. Local and private network addresses (such as `localhost` or `192.168.x.x`) are refused with a `400`. `events` can hold up to 100 items (repeats included); each event is stored once.

The response includes the endpoint `secret` — this is the **only time** it is returned. Store it immediately.

```json
{
  "id": "uuid",
  "url": "https://example.com/webhook",
  "secret": "abc123...",
  "events": ["booking.created", "booking.cancelled", "payment.created"],
  "is_active": true,
  "created_at": "2025-04-22T10:00:00Z"
}
```

### Update endpoint

```
PATCH /client/webhooks/{endpoint_id}
```

All fields are optional. Pass only what you want to change. A new `url` follows the same rules as on create.

```json
{
  "is_active": false
}
```

Returns the updated endpoint (without `secret`).

### Delete endpoint

```
DELETE /client/webhooks/{endpoint_id}
```

Returns `204 No Content`. Deletes the endpoint and all delivery records.

### List deliveries

```
GET /client/webhooks/{endpoint_id}/deliveries
```

Returns the last 50 deliveries for the endpoint, newest first.

```json
[
  {
    "id": "uuid",
    "event_type": "booking.created",
    "status": "delivered",
    "attempts": 1,
    "last_attempted_at": "2025-04-22T14:30:05Z",
    "delivered_at": "2025-04-22T14:30:05Z",
    "response_status": 200,
    "response_body": "ok",
    "created_at": "2025-04-22T14:30:00Z"
  }
]
```

Delivery `status` values: `pending`, `delivered`, `failed`, `dead`.
