Cloudbeds can send event notifications to your application every time an event occurs on a Cloudbeds property account. You can register a URL and we'll notify.
The subscription to these notifications are tied to OAuth permission scopes just like all other API calls. So during authorization process, the end-user will have approved this connection. E.g. if a subscription is made to created reservation, the permission scope read:reservation is needed.
Event life-cycle
Most events follow the same sequence, as follows:
- Myfrontdesk user triggers event notification
- Could be a reservation; or modification of a reservation’s status
- The subscribed endpoint receives JSON with details of event (view Events Payload)
- Event triggers internal logic
- Could require more information, using e.g. getReservation
- Could then send an email; or update a spreadsheet
Subscribe/Unsubscribe
Only subscribe to the events you need, the following are currently available:
- Reservation created
- Reservation status changed
- App state changed
Before subscribing, an endpoint URL will be necessary, continue only after having this set-up.
endpointURL
The endpoint URL operates similarly to the redirectURI in Cloudbed’s Web 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 a HTTP POST - 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 subscribe to an event notification, use /postWebhook. It requires the following fields:
- Event Object
- Event Action
- Endpoint URL
If successful, the response will be the SubscriptionID. This identifier must be stored in order to unsubscribe at a later date. At the moment we don't have a method that would show your subscriptions.
If the subscription to an event notification is not necessary anymore, use /deleteWebhook to unsubscribe. It requires the subscriptionID. If successful, the response to this call is only success: true.
At the moment your HTTP response code must be exactly 200. If anything else we will flag the event for retry. This behavior will soon be changed to accept 2XX.
Available objects, events and payload information
| Object | Action | Possible values | Payload | Context | Scope |
|---|---|---|---|---|---|
| reservation |
created | N/A | propertyID (integer) reservationID (integer) startDate (date) endDate (date) |
Notifies when a new reservation is created in Cloudbeds' myfrontdesk. | read:reservation |
| status_changed | in_progress, confirmed, not_confirmed, canceled, checked_in, checked_out, no_show |
reservationID (integer) status (string) |
Notifies when the reservation status is changed by user or system in Cloudbeds' myfrontdesk. | read:reservation |
|
| integration | appstate_changed | enabled pending disabled |
propertyID (integer) clientID (integer) oldState (date) newState (date) |
Notifies when app state is changed in Cloudbeds system. | Not needed. |
For other information on field names and call usage, refer to the call 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.
FAQ
If the request fails, we do retry another 2 times (so we make up to 3 requests, including the original request). They are about 1 minute apart from each other.
We say about a minute because every minute we have a retry flow that processes all failed requests. Depending on the size of the queue that could take a bit more than a minute.
We don't have a method to provide you with the list of subscriptions but we'll be adding it in the near future.
In the meantime please send us more information (EndpointURL, Object and Action) and we'll research this value and send it back to you so you.
Comments
0 comments
Please sign in to leave a comment.