Webhooks

• Webhook is a powerful tool to have Hostaway software send reservation data to 3rd party software providers with webhook support
• When you set up the webhook for your 3rd-party software, some will require you to provide an example of the reservation data to complete the setup. You can create the webhook in Hostaway and set the URL in this 3rd party software
• After this, you can make a "fake" direct booking in Hostaway under the reservations menu. This will send the data approximately 5-10 minutes later to the 3rd party so you can complete the setup
• To test webhooks and how they look in the payload, you can use this website.

Unified Webhook

Before the 1st of April 2022, we had two webhooks: one for reservations and another for guest messages. We released a new version, known as the unified webhook, which has the following advantages:

1. Users only need to subscribe to one webhook to receive updates.
2. The unified webhook supports more events than the previous reservations webhook.
3. Users can select which events they want to subscribe to for each unified webhook.

At least one event must be selected to create a new webhook. Users can also edit the selected events for webhooks that have already been created.

I’d recommend using “supports more events” instead of “triggers more events”, because now the webhook does not necessarily trigger all events — it only triggers the events selected by the user.

The unified webhook will trigger in the following cases

The unified webhook will trigger based on the events selected for that webhook.

When creating or editing a unified webhook, users can choose one or more supported events. A webhook will only send notifications for the events selected in its configuration.

The currently supported events are:

1. reservation.created
2. reservation.updated
3. message.received
4. task.created
5. task.updated

The reservation.updated event may include updates related to reservation changes, such as status, dates, listing, pricing, payment status, or door code changes.

Messaging webhooks are only triggered for guest messages, not for host messages.

Owner stay is part of the status field and does not change to "modified" when a change is made to the reservation. This behavior applies only to non-owner stay reservations. As a result, you will only receive a webhook notification when an owner stay is created or cancelled.

If the following conditions are not met, the webhook will not work

Hostaway checks 4 things in URLs when you add/update the URL of the unified webhooks in this order:

1. If the URL is valid. Constraints are here
2. If the host of the URL is in an internal network, for security purposes, to prevent access to any internal application
3. If the scheme of the URL is one of these supported schemes:
   1. HTTP
   2. HTTPS (recommended)
4. If the port (if it is given) of the URL is one of these supported ports:
   80 (default HTTP port)
   443 (default https port)

Using the unified webhook

Using the unified webhook

1. Log in as the admin account owner to your Hostaway Dashboard
2. Go to Settings > Integrations
3. Add the Webhook URL for the webhook that should be addressed
   
   
    
4. Select the events you want this webhook to subscribe to. At least one event must be selected to create a new webhook
   
   
    
5. Optionally select listings and channels, and if needed, protect the webhook with a username and password.
6. Save the webhook.

Important notes to consider:

• Unified webhooks will only trigger for the events selected in the webhook configuration.
• The webhook will trigger as soon as the most relevant data is ready. In some cases, you may see that complex fields and data that come in later are not provided at that time. We keep improving the webhook to provide more data in the payloads as well, over time.
• When using universal webhooks in combination with a public API, consider calling the API afterward to retrieve updated details not included in the webhook, where needed.
• We plan to release a public API endpoint to create and update webhooks by the end of 2022.

To be deprecated during the year 2024:

• At this moment, Hostaway also supports the 2 older webhook versions under the Reservation-specific and Messages-specific webhook modules, as well as in the API documentation
• These webhook systems are scheduled to be removed in 2024, when all clients will be asked to migrate to the new universal webhook system
• We recommend starting to use the universal webhook system in any new application built or connected.

What to do when you receive a notification about a webhook failure:

1. Go to "Settings > Integrations", scroll down on the page to the webhook section, and click on "Logs":

2. Click on the button to export the CSV

3. Open the CSV file on your computer and filter by Object ID (which is the reservation ID) and see what is stated in the "Response body" field. 

If all goes well, it will say "200"; it is an error provided by the third-party software you are integrating via webhook, and you'll need to reach out to the third-party software to ask why such an error happened

Disclaimer: If a webhook fails for more than 5 days, Hostaway may automatically disable it to protect system stability.

Editing events for an existing unified webhook

Users can edit the events selected for an existing unified webhook.

To update the event subscriptions:

1. Go to Settings > Integrations
2. Find the unified webhook you want to update
3. Edit the webhook configuration
   
   
    
4. Select or deselect the events you want the webhook to subscribe to
5. Save the changes

After saving, the webhook will only send notifications for the selected events.