ChatBedsالمطورون
Webhooks

لم تُترجم هذه الصفحة بعد، لذا فأنت تقرأ النسخة الإنجليزية.

Webhooks

Get a signed POST whenever a booking at a connected property is made, changed or cancelled, or money moves on it, from anywhere.

Instead of polling, let ChatBeds tell you when bookings change. Whenever a booking at a property is made, changed or cancelled, ChatBeds sends a signed POST to your webhook address with the whole booking. If you turn them on, it also tells you when a payment link is paid, fails, expires or is voided, and when the hotel records a refund.

Events fire for changes from anywhere: the dashboard, WhatsApp, another partner, or your own API calls.

Setting the address

You useWhere to set it
An appDevelopers → your app → Webhook. One address and one whsec_ secret for every connection. Booking events go only to connections that allowed reservations:read; payment events only to those that allowed folios:read or payments:write
A private keySettings → Partner API, on the key. Each key has its own address and secret

The address must be https and on the public internet. The secret is shown once when you save; saving again makes a new one.

Events

EventFires whenOn by default
reservation.createdA booking is madeYes
reservation.modifiedA booking's dates, guests, details, room type or rate plan change, it moves to another room, a room is assigned, or the guest checks in or outYes
reservation.cancelledA booking is cancelled, or marked a no-showYes
payment.completedA card payment link was paid (Stripe confirmed it)No
payment.failedStripe could not take the payment on a linkNo
payment.expiredA payment link closed unpaidNo
payment.voidedA payment link was voided: by payment.void, a cancellation or a shorter stayNo
payment.refundedThe hotel recorded a refund to the guestNo
reservation.checked_inA guest checked in. Also sent as reservation.modifiedNo
reservation.checked_outA guest checked out. Also sent as reservation.modifiedNo
reservation.no_showA booking was marked a no-show. Also sent as reservation.cancelledNo
folio.updatedThe bill changed: a charge, an extra, a payment taken at the desk, a line given free or voidedNo

GET /capabilities lists every event under features.webhooks, and the ones this key or app receives under features.webhook_events_on. A no-show arrives as reservation.cancelled with "status": "no_show" in the reservation (and as reservation.no_show if you turn it on), so check the status rather than the event name alone. The newer, more precise events are sent beside the general ones, never instead of them: an integration built for reservation.modified keeps getting it.

Choosing events

A key or app receives only the three reservation.* events until its developer turns others on. Existing integrations never get event types they weren't built for.

You useWhere to choose
An appDevelopers → your app → Webhook → Webhook events: tick the events. Or PATCH /api/v1/developer/apps/{id} with {"webhook_events": [...]}. The choice applies to every hotel's connection at once
A private keySettings → Partner API → the key → Webhook events. Or PUT /api/v1/partner-keys/{key_id}/webhook-events with {"events": [...]}. PUT /api/v1/partner-keys/{key_id}/webhook also takes events with the address
PATCH /api/v1/developer/apps/{id}
{
  "webhook_events": [
    "reservation.modified",
    "reservation.cancelled",
    "payment.completed",
    "payment.refunded"
  ]
}
  • Choose at least one event. An unknown event name answers 400.
  • Payment events need the app to have folios:read or payments:write among its scopes. Otherwise 400: ... folios:read or payments:write ....
  • GET /api/v1/developer/catalogue lists every webhook event, whether it is on by default, and the scopes it needs.

The request

Headers
POST /chatbeds/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: ChatBeds-Webhooks/1
ChatBeds-Event: reservation.created
ChatBeds-Delivery: c8839bfe-aa2f-4ac4-9847-d30e112516d6
ChatBeds-Signature: t=1791608987,v1=6900418cbb9ac7a69603cc6751a85d6abad4b93767052291f909c243aff58bc6
Body
{
  "id": "c8839bfe-aa2f-4ac4-9847-d30e112516d6",
  "type": "reservation.created",
  "created_at": "2026-10-10T05:09:47.298146+00:00",
  "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
  "data": {
    "reservation": {
      "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "ref": "A589DF",
      "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
      "status": "confirmed",
      "source": "PARTNER:sandbox",
      "external_ref": "BK-104233",
      "arrival": "2026-10-31",
      "departure": "2026-11-02",
      "nights": 2,
      "adults": 2,
      "children": 0,
      "guest": {
        "first_name": "Daniel",
        "last_name": "Moore",
        "email": "daniel.moore@example.com",
        "phone": "+14155550123"
      },
      "room_type": {
        "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
        "name": "Standard"
      },
      "unit": null,
      "rate_plan": null,
      "currency": "USD",
      "total": 180.0,
      "paid": 0.0,
      "balance": 180.0,
      "refund_due": 0.0,
      "payment_links": [],
      "cancellation_policy": {"id": null, "name": null, "free_cancellation_hours": null, "charge_type": "NONE", "charge_value": 0.0, "free_until": null, "free_now": true, "fee_now": 0.0, "explanation": "This hotel has no cancellation policy, so nothing is charged."},
      "cancellation": null,
      "created_at": "2026-10-10T05:09:47.271659+00:00",
      "updated_at": "2026-10-10T05:09:47+00:00"
    }
  },
  "triggered_by": "partner"
}

The body is sent compact (no spaces); it's shown formatted here.

FieldMeaning
idThe delivery's ID. Same as the ChatBeds-Delivery header, and the same on every retry
typeThe event, as in ChatBeds-Event
created_atWhen the event happened
property_idThe property. With an app, use it to find the connection
data.reservationThe booking, in the same shape as GET /reservations/{id}, as it was when the event happened
data.paymentPayment events only: the payment, in the same shape as GET /payments/{id}
triggered_bypartner when the change came through the partner API (from any partner, including you), hotel otherwise

A cancellation carries the policy's outcome:

data.reservation (reservation.cancelled, trimmed)
{
  "status": "cancelled",
  "total": 0.0,
  "paid": 100.0,
  "balance": -100.0,
  "refund_due": 100.0,
  "payment_links": [],
  "cancellation_policy": null,
  "cancellation": {
    "fee": 0.0,
    "reason": "Guest changed plans",
    "cancelled_at": "2026-10-10T05:09:47.509902+00:00"
  }
}

Payment events

A payment event carries the payment and its booking. The envelope, headers, signature and retries are the same as for booking events.

Body (payment.completed)
{
  "id": "4f1c7a2e-0d95-4b63-8e2a-7c1b9d3f5e60",
  "type": "payment.completed",
  "created_at": "2026-10-19T09:20:41.118302+00:00",
  "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
  "data": {
    "payment": {
      "id": "0b6f3d2a-91c4-4e57-8a1d-3f2e5c7b9a14",
      "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "kind": "PAYMENT",
      "amount": 180.0,
      "currency": "USD",
      "method": "STRIPE",
      "status": "COMPLETED",
      "reference": null,
      "paid_at": "2026-10-19T09:20:40.902114+00:00",
      "created_at": "2026-10-19T09:02:11.204518+00:00",
      "url": null,
      "expires_at": "2026-10-20T08:02:11.204518+00:00"
    },
    "reservation": {
      "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "ref": "A589DF",
      "total": 180.0,
      "paid": 180.0,
      "balance": 0.0
    }
  },
  "triggered_by": "hotel"
}

data.reservation is shown trimmed; it is the whole booking. payment.refunded carries the refund as the payment, with kind: "REFUND" and its amount. Refunds through Stripe are made by the hotel in its Stripe dashboard and then recorded in ChatBeds; see Refunds.

Bill events

folio.updated carries the whole bill (as folio.get gives it), its booking, and what changed: charge, extra, payment, void (including a line given free), refund or another word for the change.

Body (folio.updated)
{
  "id": "9e2b4c17-6a3f-4d08-b5e1-2c7f9a3d6e40",
  "type": "folio.updated",
  "created_at": "2026-11-05T11:20:41.118302+00:00",
  "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
  "data": {
    "folio": { "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e", "currency": "USD", "total_charges": 215.0, "total_payments": 100.0, "balance": 115.0, "lines": [], "payments": [], "windows": [] },
    "reservation": { "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e", "ref": "A589DF", "balance": 115.0 },
    "change": "payment"
  },
  "triggered_by": "hotel"
}

data.folio and data.reservation are shown trimmed.

Headers

HeaderValue
ChatBeds-EventThe event, for example reservation.created or payment.completed
ChatBeds-DeliveryThe delivery ID. Use it to ignore repeats
ChatBeds-Signaturet=<unix time>,v1=<hex HMAC-SHA256>. See Verify signatures
User-AgentChatBeds-Webhooks/1

Answering

Answer any 2xx status within 10 seconds. Anything else, a redirect, or no answer counts as a failure and is retried. See Retries and delivery.

Nothing your server does can hold up or undo a booking: the change has already happened when you hear about it.

هل تبني شيئًا؟

في هذه الصفحة