Usage Guide

Webhooks allow Hostex OpenAPI users to receive real-time data pushes when specific events occur. This guide will assist you in setting up and utilizing OpenAPI Webhooks for the following event types:

• reservation_created
• reservation_updated
• property_availability_updated
• listing_calendar_updated
• message_created
• review_created
• review_updated

Understanding Webhooks

Webhooks are a method by which an application can automatically send information to another application in response to certain events. When an event is triggered, OpenAPI sends an HTTP POST request to your specified URL, containing information about the event.

Setting Up Webhooks

To begin using OpenAPI Webhooks, you need to configure them in the OpenAPI developer console.

1. Log in to the OpenAPI Setting Page.
2. Navigate to the Webhooks settings tab.
3. Click on the "+ Add new" button.
4. Enter the URL where you want to receive Webhook notifications.

Event Types

Here are the types of events you can subscribe to and their meanings:

Event	Descrition
reservation_created	Triggered when a new reservation is made.
reservation_updated	Triggered when an existing reservation is updated.
property_availability_updated	Triggered when the availability of a property changes.
listing_calendar_updated	Triggered when a listing's calendar is updated.
message_created	Triggered when a new message is created.
review_created	Triggered when a review is created.
review_updated	Triggered when a review is updated.

🚧

We are constantly improving our API which could mean that webhook payloads may change. In order to maintain a healthy integration, your Application must parse and ignore unexpected parameters instead of rejecting the notification

Receiving and Processing Webhooks

Your Webhook URL should point to an endpoint of a web service that is set up to parse the data from the HTTP POST request and take appropriate action.

Security Considerations

When your service receives a webhook request, it will include a Hostex-Webhook-Secret-Token in the request headers. This token is unique to each webhook URL and will remain constant. It is imperative to record this token and verify its consistency with each incoming request to confirm the authenticity of the request.

⚠️

Important Security Note: Do not share the Hostex-Webhook-Secret-Token with others. Exposing this token could result in security risks. Always keep it confidential and use it solely for validation purposes.

Timeout Handling

The Webhook endpoint must acknowledge the receipt of the notification within a timeout window of 3 seconds. If the acknowledgment is not received within this time frame, the notification will not be retried. Therefore, your endpoint should be designed to process requests promptly and efficiently to avoid timeouts.

Example: Node.js Express Webhook Endpoint Handler

JavaScript

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.post('/webhook-endpoint', (req, res) => {
    const eventType = req.body.event;

    switch(eventType) {
        case 'reservation_created':
            // Handle reservation creation
            break;
        case 'reservation_updated':
            // Handle reservation update
            break;
        case 'property_availability_updated':
            // Handle property availability update
            break;
        case 'listing_calendar_updated':
            // Handle listing calendar update
            break;
        case 'message_created':
            // Handle message creation
            break;
        case 'review_created':
            // Handle review creation
            break;
        default:
            // Handle unknown event type
    }

    // Confirm receipt
    res.status(200).send('Event received');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is listening on port ${PORT}`);
});

Summary

By setting up and properly handling Webhooks, you can ensure your application responds promptly to event notifications from OpenAPI. Remember to appropriately process each event type within your application and to acknowledge events within the 3-second timeout window .