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

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)

  • 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 below.


Supported events

Event
Fired when

booking.created

A new booking is created via the Client API

booking.updated

A booking's dates, room, status, or notes are changed

booking.cancelled

A booking is deleted (treated as a cancellation)

payment.created

A new payment is recorded

payment.updated

A payment's amount, method, or description changes

message.received

An inbound OTA message (Booking.com, Airbnb) arrives


Payload envelope

Every webhook delivery sends a JSON body in this shape:

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.created / booking.updated data

Amounts are in minor units (integer cents). booking.updated from a status-only change includes only bookingId and status.

booking.cancelled data

payment.created data

Payment amounts are decimal strings (not minor units).

payment.updated data

message.received data


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.

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 automatically with exponential backoff:

Attempt
Delay after previous failure

2

1 minute

3

5 minutes

4

30 minutes

5

2 hours

Marked dead after 5 total attempts

Dead deliveries are visible in the dashboard delivery log. The id field in the payload is stable across retries — use it to deduplicate.


API reference

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

List endpoints

Returns all webhook endpoints for your property.

Create endpoint

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

Update endpoint

All fields are optional. Pass only what you want to change:

Returns the updated endpoint (without secret).

Delete endpoint

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

List deliveries

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

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

Last updated