Webhooks

With webhooks, Cloudbeds can send notifications to your application every time an event occurs on a Cloudbeds property account.

You can register your own URL endpoint which will be notified on each event and will receive a payload of event data. You can set multiple URLs for a single event or have specific ones for each event you want to listen to.

You can, for example, listen for new reservations and import them into your system as they come. You can listen to changes to room assignments and update the new room names in your interface in a matter of seconds. Or you can listen for guest information so that if a guest contact changes you have the most recent phone and email you can contact them on.

Cloudbeds events

An event is tied to a specific element of the Cloudbeds myfrontdesk app and to an action that triggered it. Thus each event carries an object and action. I.e. there is an event fired each time a reservation is created in your property. In this case, the event’s object is “reservation” and the action is “created”. Additional data can be transferred in the event’s payload such as reservation ID, dates, etc. Your application can use this data to fetch more details on a reservation by requesting it from Cloudbeds API or even perform additional actions regarding the event’s object.

Scopes

The subscription to these notifications is tied to the permission scopes just like all other API calls. So during the authorization process, the end-user will have to approve this connection.

Example: If a subscription is made to the reservation/created event, the permission scope read:reservation is needed.

Event life-cycle

Most events follow the same sequence, as follows:

  • Cloudbeds PMS triggers an event notification (usually due to the user’s action). E.g. creating a reservation
  • The subscribed endpoint receives JSON with details of the event (see Events Reference section below)
  • Your app triggered by the URL endpoint call processes internal logic.
  • Example: You can
    • Require more information using Cloudbeds API (e.g. getReservation call)
    • Send an email or update a spreadsheet

Subscribing to events

To subscribe to an event you need to know it’s object and action (e.g. reservation created). Refer to the Available Events section to find events you can subscribe to. Knowing these data you will provide the following parameters to the API call:

  • object (string) - The element of the Cloudbeds system that will fire the event.
  • action (string) - The action that you will listen to (Note: You must subscribe to a specific action. Cloudbeds doesn't support subscriptions to all actions on a given object.)
  • endpointURL (string) - Your endpoint’s URL, which will be triggered when the event occurs.

Then you need to call Cloudbeds API endpoint postWebhook Example call using cURL to subscribe to an endpoint can look like:

curl --location --request POST 'https://hotels.cloudbeds.com/api/v1.1/postWebhook' \ 
--header 'Authorization: Bearer ' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'endpointUrl=http://my-url.com/' \ 
--data-urlencode 'object=reservation' \ 
--data-urlencode 'action=created'

See Cloudbeds API docs for details.

NOTE: If you have multiple properties on account make sure you are subscribing for events for the right property. You may add a ?propertyID=12345 parameter to the request URL to subscribe for the correct property. In case of doubt, verify in the event data that the property is correct by listing your subscriptions.

Listing webhooks

In order to list your existing subscriptions, you will call the Cloudbeds API endpoint getWebhooksOn a successful call, the data returned will contain a list of your subscriptions (in the data parameter. Each subscription is a JSON object. Example output of the API call:

{
   "success": true,
   "data": [
     {
       "id": "do30k8kafl59zd",
       "key": {
         "type": "property",
         "id": 12345       },
       "event": {
         "entity": "reservation",
         "action": "created"
       },
       "subscriptionType": "webhook",
       "subscriptionData": {
         "url": "https://my.endpoint.com"
       },
     }
   ]
 }

The data property contains an array of your subscriptions (in this example there’s only one subscription) An id is your subscription identifier that is required to manage (i.e. delete) the subscription. The key parameter defines to which entity we are listening to (here it’s a property with ID 12345). The event parameter defines the object and action of events that will trigger your endpoint URL which is defined in the subscriptionData parameter. Refer to Cloudbeds API docs for details.

Unsubscribing and deleting webhooks
You can delete a subscription by calling the deleteWebhook and providing the subscriptionID parameter. You can find your subscription ID by listing your existing subscriptions (see the previous section). On successful deletion, your endpoint will no longer be triggered by the event you were subscribed to.

Unsubscribing and deleting webhooks

You can delete a subscription by calling the [deleteWebhook](https://hotels.cloudbeds.com/api/v1.2/docs/#tag/Integration/paths/~1deleteWebhook/delete) and providing the subscriptionID parameter. You can find your subscription ID by listing your existing subscriptions (see the previous section). On successful deletion, your endpoint will no longer be triggered by the event you were subscribed to.

Your URL Endpoint

The endpoint URL operates similarly to the redirectURI in Cloudbeds API (where we securely forward authorization codes to your server). The configured endpoint is where all notifications will be posted to and can be configured differently for each event type. This endpoint will receive an HTTP POST request containing JSON data payloads.

The volume of requests this endpoint will receive depends solely on the size of the properties and what different events will be subscribed to.

Your endpoint is called by the Cloudbeds notification system using a POST HTTP request. To confirm a successful call it should return any of the 2XX HTTP responses (i.e. 200 OK, 201 Accepted, etc).

Failed notifications and retry policy

If there’s a failure during a call to your endpoint (server unavailable, return code different than 2XX, etc.) the endpoint will be called again after a one-minute delay. Retries with a one-minute delay will be repeated until a request is successful or a limit of five attempts is reached. If your endpoint returns an error for all attempts no further calls will be made for this event. New events triggered by the Cloudbeds myfrontdesk app will still try to call your endpoint and will follow the same retry policy.

Notification payload

Your endpoint will receive the following data in each payload.

Version

Payload format may change in the future and any change will be reflected in the version number. If you receive a payload with an unknown version make sure to verify you’re able to parse the new payload. The general rule for versioning is that the whole number denotes a potentially breaking change, and the decimals denote minor changes. You can track any changes in our Changelog. See example payloads for each event for version format.

Event

A shortened information about the type of event that triggered the notification. This contains object and action in one string i.e. reservation/created. See example payloads for each event for possible content.

Timestamp

A timestamp describing the time when the event was created. This means that it’s a point in time when the event occurred in myfrontdesk. If notification gets delayed in retries after failure the timestamp will still show the original event time. The timestamp is in the format of UNIX timestamp with microseconds i.e 1611758157.431234. See example payloads for each event for timestamp format.

NOTE: The order of payload fields may be different than the example payloads provided in this documentation.

Testing Webhooks

To test the webhooks, we suggest using https://webhook.site

An endpointURL is created as soon as you enter the page. With it you may test the responses and errors that our calls return.

You receive the request details, the response headers and body for each call made to the given endpointURL.

Events reference

Make sure to pay attention to the payload as there are inconsistencies in the parameter spelling. e.g. propertyID versus propertyId.

NOTE I: We strongly recommend not use webhooks as a trigger to refresh the token pair as they can come in simultaneously and cause invalidation of tokens.

NOTE II: Some duplicates are expected, because one event can trigger several webhooks.

Example: accommodation_type_changed will influence the accommodation_changed and assigned because if you remove the room type, the room assignment will also be removed.

1reservationcreatedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/created", "propertyID": 12345, "propertyID_str": 12345, "reservationID": 31415926, "startDate": "2020-05-19", "endDate": "2020-05-21" }Notifies when a new reservation is created in Cloudbeds myfrontdesk or by a third party app.read:reservation
2status_changedin_progress confirmed not_confirmed canceled checked_in checked_out no_show{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/status\_changed", "propertyID": 12345, "propertyID_str": 12345, "reservationID": 31415926, "status": "confirmed" }Notifies when the reservation status is changed by user or system in myfrontdesk.read:reservation
3dates_changedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/dates_changed", "propertyId": 12345, "propertyId_str": "12345", "reservationId": 31415926, "startDate": "2020-05-19", "endDate": "2020-05-21" }Notifies when the stay dates of reservation were changed by the user or system in Cloudbeds myfrontdesk app.read:reservation
4accommodation_status_changedoccupied unoccupied{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/accommodation_status_changed", "propertyId": 12345, "propertyId\_str": 12345, "reservationId": 31415926, "roomId": "13", "status": "occupied" }Notifies when the accommodation unit (e.g. room, not room type) was changed by the user, system, or third party. Accommodation units can have status either occupied or unoccupied independent from the reservation status.read:reservation
5accommodation_type_changedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/accommodation_type_changed", "propertyId": 12345, "propertyId\_str": 12345, "reservationId": 31415926, "roomTypeId": 345 }Notifies when the accommodation type (not unit) was changed on a reservation by the user or a third party. If multiple accommodation types were changed the roomTypeID will reflect only one of the changed types, make sure to get the reservation and import the changes.read:reservation
6accommodation_changedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/accommodation_changed", "propertyId": 12345, "propertyId_str": 12345, "reservationId": 31415926, "roomId": "13" }Notifies when a reservation had any accommodation unit (e.g. room) reassignments in Cloudbeds myfrontdesk app done by the user, third party, or system.read:reservation
7deletedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "reservation/deleted", "propertyId": 12345, "propertyId_str": "12345", "reservationId": 31415926 }Notifies when the reservation was deleted from the Cloudbeds system by the user.read:reservation
8notes_changed (new)N/A{ "reservationId": "6954439751495", "propertyId": "12345", "notes": "This is a note", "version": "1.0", "event": "reservation/notes_changed", "timestamp": 1723019974.374369 }Notifies when a reservation note is created or modified.read:reservation
9guestcreatedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "guest/created", "propertyId": 12345, "propertyId_str": "12345", "guestId": 35436, "guestId_str": "35436" }Notifies when a new guest was created in Cloudbeds myfrontdesk app by a user or a third party. The guest can be created when creating a new reservation or when adding additional guests.read:guest
10assignedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "guest/assigned", "propertyId": 12345, "propertyId_str": "12345", "guestId": 35436, "guestId_str": "35436", "reservationId": 31415926, "roomID": "13" }Notifies when a new guest or an existing guest is added to the reservation by the user or third party. This notification will duplicate the notifications for “new guest created” when a new guest is being added to the reservation.read:guest
11removedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "guest/removed", "propertyId": 12345, "propertyId_str": "12345", "guestId": 35436, "guestId_str": "35436", "reservationId": 31415926, "roomID": "13" }Notifies when a guest is removed from a reservation by a user or third party.read:guest
12details_changedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "guest/details_changed", "propertyId": 12345, "propertyId_str": "12345", "guestId": 35436, "guestId_str": "35436" }Notifies when any guest information (including the number of reservations for this guest) has been edited or changed on the Guest tab within the reservation by the user, system, or a third party.read:guest
13accommodation_changedN/A{ "version": "1.0", "timestamp": 1611758157.431234, "event": "guest/accommodation_changed", "propertyId": 12345, "propertyId_str": "12345", "guestId": 35436, "guestId_str": 35436, "reservationId": 31415926, "roomId": "13" }Notifies when an accommodation unit (e.g. room) was changed on the Guest tab within a reservation or when any other accommodation unit reassignment happened by the user or system.read:guest
14integrationappstate_changedenabled pending disabled installing{ "version": "1.0", "timestamp": 1611758157.431234, "event": "integration/appstate_changed", "propertyID": 12345, "propertyID_str": "12345", "clientID": 1234, "oldState": "enabled", "newState": "disabled" }Notifies when app state is changed in Cloudbeds system.Not needed.
15api_queue_taskrate_status_changedin_progress completed error{ "version": "1.0", "queueTaskId": 11111, "queueTaskId_str": 11111, "timestamp": 1611758157.431234, "event": "api_queue_task/rate_status_changed", "propertyId": 12345, "propertyId_str": 12345, "status": "completed" }Notifies when the status of a rate batch job submitted with /putRate changes: eg. in_progress -> completed. The queueTaskId corresponds to the jobReferenceID in the /putRate response.read:rate
16roomblockcreatedblocked_dates out_of_service{ "version": "1.0", "roomBlockID": "169266429834303645", "propertyID": 12345, "roomBlockType": "out_of_service", "roomBlockReason": "test", "startDate": "2023-08-28", "endDate": "2023-08-30", "rooms": [ { "roomID": "445566-1", "roomTypeID": 445566 } ], "event": "roomblock/created", "timestamp": 1611758157.431234}Notifies when a new room block has been created.read:roomBlock
17roomblockremovedblocked_dates out_of_service{ "version": "1.0", "roomBlockID": "169266429834303678", "propertyID": 12345, "event": "roomblock/removed", "timestamp": 1611758157.431234 }Notifies when an existing room block has been deleted.read:roomBlock
18roomblockdetails_changedblocked_dates out_of_service{ "version": "1.0", "roomBlockID": "169266429834303646", "propertyID": 12345, "roomBlockType": "out_of_service", "roomBlockReason": "test", "startDate": "2023-08-28", "endDate": "2023-08-30", "rooms": [ { "roomID": "445566-1", "roomTypeID": 445566 } ], "event": "roomblock/details_changed", "timestamp": 1611758157.431234 }Notifies when an existing room block has been updated.read:roomBlock
19allotmentBlockcreatedtentative definite{ "version": "1.0", "propertyID": 12345, "propertyID_str": 12345, "groupID": 11528, "groupID_str": 11528, "allotmentBlockCode": "b35250", "status": "tentative", "event": "allotmenBlock/created", "timestamp": 1611758157.431234 }Notifies when an allotment block has been created.read:allotmentBlock
20allotmentBlockupdatedtentative definite cancelled{ "version": "1.0", "propertyID": 12345, "propertyID_str": 12345, "groupID": 11528, "groupID_str": 11528, "allotmentBlockCode": "b35250", "status": "definite", "event": "allotmenBlock/updated", "timestamp": 1611758157.431234 }Notifies when an allotment block has been modified.read:allotmentBlock
21allotmentBlockdeleteddeleted{ "version": "1.0", "propertyID": 12345, "propertyID_str": 12345, "groupID": 11528, "groupID_str": 11528, "allotmentBlockCode": "b35250", "status": "deleted", "event": "allotmenBlock/deleted", "timestamp": 1611758157.431234 }Notifies when an allotment block has been deleted.read:allotmentBlock
22transactioncreatedTransaction category: adjustment, addon, custom_item, fee, payment, product, rate, room_revenue, refund, tax, void{ "propertyID": 12345, "propertyID_str": "12345", "transactionID": "5893027203649579", "transactionID_str": "5893027203649579", "parentTransactionID": "5893027203649578", "parentTransactionID_str": "5893027203649578", "transactionCategory": "payment", "category": "cash", "version": "1.0", "event": "transaction/created", "timestamp": 1710340353.307892 }Notifies when a new transaction has been created.read:payment
23reservationinvoice_requestedAvailable to tech partners in the Government Invoicing and Fiscalization only.{ "propertyID": 12345, "propertyID_str": "12345", "invoiceID": "38386948", "version": "1.0", "event": "reservation/invoice_requested", "timestamp": 1712746049.608115}Notifies when a new invoice has been requested.read:reservation
24reservationinvoice_void_requestedAvailable to tech partners in the Government Invoicing and Fiscalization only.{ "propertyID": 12345, "propertyID_str": "12345", "reservationID": "0224437197337", "invoiceID": "38386948", "version": "1.0", "event": "reservation/invoice_void_requested", "timestamp": 1712748256.580032}Notifies when a new credit note has been requested.read:reservation
25housekeepinghousekeeping_reservation_status_changed (new)confirmed not_confirmed canceled checked_in checked_out no_show{ "propertyId": 12345, "roomId": "356713-1", "newStatus": "checked_in", "previousStatus": "confirmed", "startDate": "2024-07-01", "endDate": "2024-07-02", "version": "1.0", "event": "housekeeping/housekeeping_reservation_status_changed", "timestamp": 1712748256.580032}Notifies of reservation status changes based on the "roomId"read:housekeeping
26housekeepinghousekeeping_room_occupancy_status_changed (new)occupied vacant{ "propertyId": 12345, "roomId": "356713-1", "newStatus": "occupied", "previousStatus": "vacant", "startDate": "2024-07-01", "endDate": "2024-07-02", "version": "1.0", "event": "housekeeping/housekeeping_room_occupancy_status_changed", "timestamp": 1712748256.580032}Notifies of room occupancy changes related to room blocksread:housekeeping
27integrationappsettings_changed{ "propertyId": 12345, "propertyID_str": "12345", "clientID": "app_VisTh9b2YzfjiJJ4Z", "propertyId": 12345,
"clientId": "app_VisTh9b2YzfjiJJ4Z",
"version": "1.0",
"event": "integration/appsettings_changed",
"timestamp": 1733343749.207773 }
Notifies when the app settings are modifiedread:appPropertySettings

For other information on field names and call usage, refer to the call documentation.