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:

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

{
  "bookingId": "abc-123",
  "status": "new",
  "room": "uuid-of-room",
  "total": 18000,
  "dates": [
    { "date": "2025-06-01", "amount": 9000 },
    { "date": "2025-06-02", "amount": 9000 }
  ]
}

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

booking.cancelled data

{ "bookingId": "abc-123" }

payment.created data

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

Payment amounts are decimal strings (not minor units).

payment.updated data

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

message.received data

{
  "bookingId": "abc-123",
  "messageId": "channex-message-uuid",
  "threadId": "channex-thread-uuid",
  "content": "Hi, can I check in early?"
}

---

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.

// 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 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 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

GET /client/webhooks

Returns all webhook endpoints for your property.

[
  {
    "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

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

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

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

{
  "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.

[
  {
    "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.