Cette page n’est pas encore traduite : vous lisez la version anglaise.
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 use | Where to set it |
|---|---|
| An app | Developers → 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 key | Settings → 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
| Event | Fires when | On by default |
|---|---|---|
reservation.created | A booking is made | Yes |
reservation.modified | A 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 out | Yes |
reservation.cancelled | A booking is cancelled, or marked a no-show | Yes |
payment.completed | A card payment link was paid (Stripe confirmed it) | No |
payment.failed | Stripe could not take the payment on a link | No |
payment.expired | A payment link closed unpaid | No |
payment.voided | A payment link was voided: by payment.void, a cancellation or a shorter stay | No |
payment.refunded | The hotel recorded a refund to the guest | No |
reservation.checked_in | A guest checked in. Also sent as reservation.modified | No |
reservation.checked_out | A guest checked out. Also sent as reservation.modified | No |
reservation.no_show | A booking was marked a no-show. Also sent as reservation.cancelled | No |
folio.updated | The bill changed: a charge, an extra, a payment taken at the desk, a line given free or voided | No |
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 use | Where to choose |
|---|---|
| An app | Developers → 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 key | Settings → 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 |
{
"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:readorpayments:writeamong its scopes. Otherwise400:... folios:read or payments:write .... GET /api/v1/developer/cataloguelists every webhook event, whether it is on by default, and the scopes it needs.
The request
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{
"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.
| Field | Meaning |
|---|---|
id | The delivery's ID. Same as the ChatBeds-Delivery header, and the same on every retry |
type | The event, as in ChatBeds-Event |
created_at | When the event happened |
property_id | The property. With an app, use it to find the connection |
data.reservation | The booking, in the same shape as GET /reservations/{id}, as it was when the event happened |
data.payment | Payment events only: the payment, in the same shape as GET /payments/{id} |
triggered_by | partner when the change came through the partner API (from any partner, including you), hotel otherwise |
A cancellation carries the policy's outcome:
{
"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.
{
"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.
{
"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
| Header | Value |
|---|---|
ChatBeds-Event | The event, for example reservation.created or payment.completed |
ChatBeds-Delivery | The delivery ID. Use it to ignore repeats |
ChatBeds-Signature | t=<unix time>,v1=<hex HMAC-SHA256>. See Verify signatures |
User-Agent | ChatBeds-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.
Vous créez quelque chose ?
Test tools (staging)
Reset the test hotel, move its clock, send yourself webhook events and replay them, read the API log, and simulate card payments and guests' WhatsApp messages. Staging only.
Verify signatures
Check that every webhook comes from ChatBeds and was not changed or replayed, with code for Node.js and Python.