Using liteAPI webhooks

Introduction

liteAPI webhooks let your application react to hotel and flight 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, amendment, or flight booking state changes) 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 (hotels and flights, where enabled)
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 hotel or flight 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 hotel and flight 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 — especially hotel versus flight — can use different payload shapes inside request and response.

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 hotel booking lifecycle and booking-management workflows, and flight booking lifecycle events where flight booking is enabled on your account. 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.

Hotel 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

booking.checkinInstruction

Triggered when check-in instructions for the guest become available or are updated (for example hotel-supplied arrival details, access codes, or front-desk notes).

Typical uses:

Sending pre-arrival communications to guests
Surfacing check-in details in your app or itinerary views

Booking API errors

For failures during core hotel booking API steps, liteAPI exposes three webhook events (there are no separate _error events for amendments, rebooks, refunds, compensation, or hotel confirmation number updates in the event catalog today):

booking.prebook_error

Triggered when the prebook step fails (for example availability, validation, or supplier error).

Typical uses:

Monitoring and alerting on funnel breakage before payment
Customer support workflows when checkout fails

booking.book_error

Triggered when the confirm/book step fails (for example payment, validation, or supplier rejection).

Typical uses:

Recovering abandoned carts or retry flows where appropriate
Alerting when confirmations drop unexpectedly

booking.cancel_error

Triggered when a cancellation request fails or is rejected.

Typical uses:

Ops alerting when a cancel cannot be completed
Syncing internal state when cancel flows fail

Amendment and booking-management events

If you have agents on your account who handle support, these webhooks allow you to track amendments and related actions on existing bookings.

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 the client (usually related to relocation or an issue with the room)

Flight booking events

Where flight booking is enabled, you can subscribe to flight lifecycle events. Payload shapes may differ from hotel webhooks; branch on event_name and parse stringified request / response per event.

flight.prebook — Flight prebook session created or updated (availability and pricing before payment).

flight.attachServices — Ancillary services attached to a flight prebook or booking (for example seats or baggage).

flight.book.created — Flight booking record created (initial persistence after the book flow starts).

flight.book.pending.confirmation — Booking awaits supplier or airline confirmation.

flight.book.confirmed — Flight booking confirmed by the supplier.

flight.book.cancelled — Flight booking cancelled successfully.

flight.book.failed — Flight booking could not complete (supplier rejection or other failure).

flight.book.expired — Offer or session expired before completion (timeout or stale prebook).

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, or flight.book.confirmed).

request

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

response

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

sandbox

Set to true or false. Use this to determine which environment triggered the webhook. (true = sandbox, false = production)

⭐️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\": [ … ] }",
  "sandbox": false
}

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