Webhooks

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.

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