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.

API-created webhooks and disconnection

POST /webhooks returns data.id and data.secret_token once, in the creation response. Save the secret securely and compare incoming Hostex-Webhook-Secret-Token headers against it. Query and update endpoints never return it; if lost, delete and recreate the webhook. Each webhook record has its own secret, which changes when it is recreated.

Call GET /accounts/me after authorization to save the stable string account_id. Main-account and sub-account authorizations share that ID. For ordinary business events, map each configured webhook endpoint to its saved account ID.

When the host disconnects your application in Hostex, or your application revokes its OAuth connection, Hostex deletes webhooks created through the API by your application for that account. Manual webhooks, legacy records without an application ownership marker, and other applications' webhooks are retained. For public OAuth clients with multiple device tokens, revoking one device does not disconnect the application while another token remains; revoking the last one does. Host-initiated application disconnection revokes all its devices.

This lifecycle event is automatic and is not a selectable value in the events filter. A final authorization_revoked event is sent to each deleted webhook's saved URL using its original secret, even if its business-event filter excludes this event. The payload includes account_id, client_id, a ULID string event_id and UTC timestamp. No notification can be sent if your application has no owned webhook. Existing queued business events are skipped once the webhook is removed. Requests already in flight cannot be recalled and may arrive after the final notification; treat your local connection as revoked and ignore subsequent business events until reauthorization.

This notification uses the same timeout, immediate transport retries and circuit breaker described below. It is best effort, with no delayed replay or guaranteed delivery. Its event_id stays the same for retries; process it idempotently. Connection revocation and webhook deletion take effect even if notification delivery fails. After reconnecting, create new webhooks and save their new secrets.

Event Types

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

🚧

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 record and remains constant until that record is deleted. 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

Each notification is sent to your URL as an HTTP POST. Hostex waits up to 3 seconds to connect to your endpoint and up to 5 seconds in total for the response.

• Transport failures are retried immediately. If the request cannot be completed — the connection is refused or times out, DNS or TLS fails, or no response arrives within 5 seconds — Hostex retries right away, with no delay between attempts. A notification gets at most 3 attempts in total.
• Retries may come from a different IP address than the first attempt. Do not accept webhooks only from a single allow-listed IP; authenticate requests with Hostex-Webhook-Secret-Token as described above.
• Any HTTP response counts as delivered, including 4xx and 5xx. Hostex does not look at the status code, so answering with an error status does not cause a retry.
• Configure the final HTTPS URL. Hostex follows redirects, but a 301, 302 or 303 redirect turns the request into a GET without a body, and whatever the redirect target answers still counts as delivered.
• There is no delayed redelivery. If every attempt fails, the notification is dropped. It is not queued for later and cannot be replayed.
• Endpoints that keep failing are paused. When deliveries to the same URL keep failing, Hostex stops sending to it for a while. Notifications that occur during the pause are dropped, not sent later.
• The same notification can arrive more than once. For example, if your endpoint handles a request but answers after the 5-second limit, the retry delivers it again.

To stay in sync:

• Answer with a 2xx status as soon as the request is received, and do any slow work asynchronously (for example in your own queue).
• Make processing idempotent using event_id. Every v3 notification includes a 26-character ULID string. All webhook URLs for the same event and all retries share the same ID; distinct emitted events have different IDs. Store processed IDs and skip duplicates. The ID does not guarantee delivery or ordering, and does not identify the affected resource or originating API request.
• Do not rely on webhooks alone. Periodically reconcile by reading the current state through the API — for example GET /reservations, GET /conversations, GET /reviews, GET /availabilities or POST /listings/calendar — to pick up anything that was not delivered.

Example: Node.js Express Webhook Endpoint Handler

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;
        case 'review_updated':
            // Handle review update
            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, to acknowledge each request with a 2xx status well within the 5-second limit, and to reconcile periodically through the API, because notifications that fail to be delivered are not sent again.