Webhooks Overview
A summary of the webhook notifications provided by Guesty.
Guesty's Open API allows you to send various webhook notifications to your application's notification URL(s).
Figure 1: Webhook Subscription Flow.
A webhook is a mechanism that allows an app to send real-time data to other apps. A webhook sends data to other applications in real-time, so you get it immediately. This structure is much more efficient than the traditional approach to requesting data from an API endpoint in some use cases.
Understanding and consuming webhooks is essential in getting the best out of Guesty's Open API.
Why Create Webhooks?
Once your Guesty Open API integration is complete and has finished its initial data synchronization, we recommend using webhook notifications to stay up to date. Webhook notifications will help you save time and resources, and you can synchronize only the data that has changed, ignoring that which has remained in the same state since the initial synchronization.
For instance, you can create a webhook for new reservations and be notified whenever a new one is created. Our Open API offers a wide variety of webhook events in addition to new reservation notifications.
Table of Supported Webhooks
The following table summarizes the Webhooks that Guesty makes available, with links to more detailed guides for each type.
| Webhook Domain | Webhook Event |
|---|---|
| Reservation Webhooks | reservation.new, reservation.updated |
| Message Webhooks | reservation.messageReceived, reservation.messageSent |
| Payment Webhooks | payments.received, payments.failed, payments.refunded, payments.overdue, payments.overcharged, payments.overcharge.expected, payments.authenticationRequired, payments.authorizationHoldFailed, payments.disputes |
| Listing Webhooks | listing.new, listing.updated, listing.removed |
| Calendar Webhooks | listing.calendar.updated, calendar.updated.v2 |
| Task Webhooks | task.created, task.updated, task.deleted |
| Guest Webhooks | guest.created, guest.updated, guest.deleted |
Retry Schedule
Guesty attempts to deliver each webhook message using a retry schedule with exponential backoff. Each message is retried according to the following schedule, with each period starting after the failure of the preceding attempt:
- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- 10 hours (in addition to the previous)
If an endpoint is removed or disabled, delivery attempts to that endpoint will be disabled as well. For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds after the first attempt.
Indicate successful delivery
To indicate that a webhook has been processed, return a
2xxstatus code (200-299) within a reasonable time frame (15s). Any other status code, including3xxredirects, is treated as a failure.
Failed delivery handling
After the above attempts are concluded, the message will be marked as Failed for this endpoint. If all attempts to a specific endpoint fail for 5 days, the endpoint will be disabled. The clock starts only after multiple deliveries fail within a 24-hour span, with at least a 12-hour gap between the first and last failures.
Contact Guesty API Support to request reactivation of your disabled webhook subscription.
How to Subscribe to Webhooks
To subscribe to the relevant Webhook events, follow the developer documentation here.
FAQs
What is considered an error on the part of the recipient endpoint?
The nature of a webhook is that it doesn't wait for a reply from the recipient. If the recipient is unresponsive, the delivery will fail.
How long after an event will I receive the webhook?
Webhooks can be received from a few seconds to 30 minutes after the event has taken place on your Guesty account. If you're encountering delays in excess of half an hour, please contact support.
Why am I receiving two webhooks for the same reservation update?
To ensure all reservation changes are captured after the event, two webhooks are generated. They differ in content, and we recommend you analyze their schema and content to map with your systems.
Why am I receiving webhooks for old Airbnb messages?
When a property is imported from Airbnb or linked with an existing Airbnb listing, Guesty will import past, current, and future reservations and their related conversation threads. Since these conversations are new to Guesty, they will trigger the reservations.messageReceived webhook. Learn how Guesty syncs with the booking channels here.
Why don't new reservations trigger calendar webhooks?
Currently, our webhooks only include specific updates. The listing.calendar.updated event will be triggered only under the following circumstances:
- Changes in availability through calendars.
- Updates to nightly rates.
- Alterations to the minimum stay requirement.
This does not include notifications for calendar updates caused by new or altered reservations.
Updated 2 days ago