Using liteAPI webhooks

Introduction

liteAPI webhooks let your application react to booking activity as it happens — without polling, scheduled jobs, or manual reconciliation.

Instead of repeatedly querying the API to check whether something changed, you can subscribe to specific events (like a prebook, confirmed booking, cancellation, or amendment) and receive a real-time HTTP request whenever that event occurs.

This makes webhooks ideal for:

Keeping your internal booking state in sync with liteAPI
Triggering downstream workflows (emails, CRM updates, analytics, fulfillment)
Monitoring booking and booking-management activity programmatically

How liteAPI webhooks work (at a glance)

You register an HTTPS endpoint in the liteAPI dashboard
You choose which events you want to receive
When one of those events occurs, liteAPI sends a POST request to your endpoint
Your system processes the payload and responds with a 2xx status code

That’s it. There’s no special handshake, no long-lived connection, and no additional infrastructure required.

When should you use webhooks?

Use webhooks when you need to:

React immediately to booking lifecycle changes
Keep external systems in sync without polling
Track booking amendments or cancellations reliably
Validate that booking flows (like prebook → book) are working end-to-end

If you only need data on demand, direct API calls are usually enough.
If you need to respond to changes, webhooks are the right tool.

What this guide covers

This guide walks you through:

Setting up your first webhook endpoint
Subscribing to booking-related events
Testing your setup in minutes using a public webhook receiver
Understanding webhook payloads and common integration patterns
Known limitations and current constraints to be aware of

You can jump straight to the quick start if you want to see your first event fire right away, or scroll down to the following sections for more details on the fields and process.

Quick Start: Receive Your First Event in 5 Minutes

This quick start walks you through receiving a real webhook event from liteAPI using a public test endpoint. You don’t need to write any backend code to validate that your setup works.

By the end of this section, you’ll see a live webhook payload arrive in real time.

Step 1: Create a test webhook endpoint

For quick validation, we recommend using https://webhook.site/.

Open https://webhook.site/ and leave it open in a tab
Copy the unique webhook URL generated for you
(for example: https://webhook.site/xxxx-xxxx-xxxx)

This URL will display every request it receives, making it ideal for testing.

Step 2: Register the webhook in the LiteAPI dashboard

Go to Developer tools → Webhooks in the LiteAPI dashboard
Click Register Endpoint
Fill in the following fields:
- Webhook URL: paste the webhook.site URL
- Description: e.g. Prebook test webhook
- Authentication Token: leave empty
- Retry settings: leave defaults for now
Under Event Subscriptions, select: booking.prebook
Click Register Webhook

Your endpoint is now active.

Step 3: Trigger a prebook event

To trigger a booking.prebook event:

Open your LiteAPI whitelabel booking site
Search for a hotel
Select a room

Room selection automatically triggers a prebook request.

Step 4: Verify the webhook delivery

Go back to your webhook.site page.

You should see a new incoming request containing:

An event_id
An event_name set to booking.prebook
A request and response payload

If you see the event arrive, your webhook is working correctly 🎉

If you don’t see anything

Quick things to check:

The webhook endpoint is enabled
booking.prebook is selected in event subscriptions
The webhook URL is copied correctly (no trailing spaces)
Your project/environment matches the whitelabel you’re testing

Once this works, you’re ready to move beyond testing and start handling webhooks in your own application.

Registering a Webhook Endpoint in the Dashboard

Once you’ve confirmed that webhooks work end-to-end, you’ll want to configure your endpoint properly for ongoing use. This section explains each option in the LiteAPI webhook configuration and when it matters.

You can access webhook settings from the LiteAPI dashboard at:

Developer tools → Webhooks

From here, you can register new endpoints, edit existing ones, enable or disable delivery, and adjust retry behavior.

Webhook configuration fields

When registering (or editing) a webhook endpoint, you’ll see the following fields.

Webhook URL

The HTTPS endpoint LiteAPI will send events to.

Must be publicly reachable
Must respond with a 2xx status code to acknowledge receipt

⭐️ Note: The 2xx response is so the system knows not to keep retrying according to your retry settings.

Description

A free-text label to help you identify the webhook.

Authentication Token

An optional shared secret sent with each webhook request as the value for authorization in the header.

Useful for validating that requests originate from liteAPI
Typically checked via a request header in your handler
Strongly recommended for production environments

Retry configuration

LiteAPI retries webhook delivery automatically when your endpoint does not return a successful response.

Max retries
The maximum number of retry attempts before the event is dropped.

Initial wait (seconds)
The delay before the first retry attempt.

Retries use exponential backoff, meaning subsequent retries wait longer between attempts.

For most use cases, the default values are sufficient.

Event subscriptions

This determines which events will be sent to your endpoint.

You can subscribe to multiple events per webhook, but routing logic will be needed as different events have different response formats.

Custom request headers

You can attach additional HTTP headers to every webhook request.

Typical uses include:

Passing environment identifiers
Adding correlation IDs
Supporting internal routing or logging

These headers are static and sent with every event.

Managing existing endpoints

From the Webhooks list view, you can:

Enable or disable an endpoint without deleting it
Edit configuration details
Update subscribed events

Events You Can Subscribe To

LiteAPI webhooks are organized around the booking lifecycle and booking management workflows. Each event represents a meaningful state change that your application may want to react to.

You can subscribe to multiple events on a single webhook endpoint, but we recommend starting with the minimum set needed for your use case and expanding as needed.

Booking Lifecycle Events

booking.prebook

Triggered when a user selects a room, and liteAPI performs a prebook request.

Typical uses:

Useful for testing, but generally far too noisy to be useful for production.

booking.book

Triggered when a booking is successfully confirmed.

Typical uses:

Create or update an internal booking record
Send confirmation emails or messages
Trigger downstream fulfillment workflows

booking.cancel

Triggered when a user cancels their booking.

Typical uses:

Update internal booking records

booking.book.hotelConfirmationNumber

Triggered when the hotel confirmation number is added or updated.

Typical uses:

Syncing confirmation numbers to customer-facing systems
Updating itineraries or vouchers

Error events

Most booking-related events have corresponding *_error variants.

These are typically used for:

Monitoring and alerting
Customer support workflows
Automated retries or fallbacks (where appropriate)

Amendment Events

If you have agents on your account who handle support, these webhooks allow you to track any amendments to existing bookings in the system.

booking.rebook.rfn - A refundable room is rebooked

booking.rebook.nrfn - A non-refundable room is rebooked

booking.amendment - Changes to the booking information, like guest name or special requests

booking.amendment.relocation - Due to unforeseen circumstances, the guest is relocated

booking.refund - A refund is issued for the booking

booking.compensation - Compensation is given to client. (Usually related to relocation or an issue with the room)

Payload Schema and Structure

Every LiteAPI webhook request delivers an event envelope with a consistent top-level shape. Inside that envelope, the request and response fields contain the event-specific data.

Event envelope (top-level fields)

Each webhook payload includes:

event_id

A unique identifier for the webhook event delivery. Use this for deduplication and idempotency.

event_name

The event type (for example: booking.prebook, booking.book, booking.amendment).

request

A JSON string containing the request data associated with the event.

response

A JSON string containing the response data associated with the event.

⭐️Important
request and response are stringified JSON, not JSON objects.
Your webhook handler must parse them before accessing fields.

Example structure (simplified)

{
  "event_id": "…",
  "event_name": "booking.prebook",
  "request": "{ \"offerId\": \"…\", \"clientReference\": \"…\" }",
  "response": "{ \"prebookId\": \"…\", \"hotelId\": \"…\", \"roomTypes\": [ … ] }"
}

In most languages, you’ll do this in two steps:

Parse the webhook body into an object
Parse request and response again (because they are strings)

Idempotency and duplicates

Webhook delivery should be treated as at-least-once:

If LiteAPI does not receive a 2xx response, it may retry
Retries can result in the same event being delivered more than once

To safely handle this, your system should:

Store event_id after successful processing
Ignore or short-circuit if the same event_id is received again

A simple mental model:

event_id = delivery identity
Deduplicate by event_id
Ensure your processing is safe to run more than once

Known Issues

No environment support
There is not yet a programmatic way to distinguish sandbox vs production events in webhook payloads. This is in progress.

For now, most integrations differentiate environments operationally (for example, by:

Using data in the request itself to determine if it is a test. For instance, the hotelConfirmationCode of a sandbox book request will always return: \"hotelConfirmationCode\":\"test\"
Maintaining separate LiteAPI projects for sandbox vs production)

The manage booking endpoints can have a slight delay

We use a DB replica to speed up the manage booking endpoints. If you make a call to them immediately after a booking operation, the full record may not be updated. In that case, add a 30s delay. However you should usually be able to just use the webhooks payload to perform the action and not need a separate call.