Version: 1.0.10
Last Updated: 7th Oct, 2026

BookingWhizz Webhooks API Documentation

Introduction

Welcome to the BookingWhizz Webhooks API, designed for seamless integration with hospitality management systems. This API enables hotels, property management systems (PMS), and travel platforms to centralize guest profiles, reservations, and stay data for improved guest experience, booking automation, loyalty programs, and revenue tracking.

How It Works

The API consists of three main webhook endpoints:

  • Guest Profile Webhook – Captures guest details and preferences.
  • Reservation Webhook – Manages reservation data including check-in/out, source tracking, and market segmentation.
  • Stay Data Webhook – Tracks room charges, payments, and revenue for loyalty programs and financial insights.

All webhook requests require authentication headers (Client ID & Password) and must be formatted in JSON.

Authentication

Each request is authenticated with two custom HTTP headers: client-id and password. This is not HTTP Basic Authentication, so do not send an Authorization header. Requests with missing or wrong credentials receive 401 Un Authorize.

Validation

Requests are validated before anything is saved:

  • The body must be JSON: a single object, or an array of objects to send several records at once. Invalid or empty JSON is rejected with 400.
  • Every field marked Required in the tables below must be present and not empty. Dates use YYYY-MM-DD, timestamps use YYYY-MM-DD HH:mm:ss, and departureDate cannot be before arrivalDate.
  • status must be one of the listed values (stays: CHECKED_OUT). Each booking or stay needs at least one entry in roomDetails, and every room needs at least one guest in guestProfile. The first guest of each room is that room's primary guest and must have an id.
  • If any record fails, the whole request is rejected with 422 and nothing is saved. The response lists every problem, per record, so you can fix them and resend the whole request.

Example 422 response:

{"success": false, "message": "Validation failed. Nothing was saved.", "errors": [{"index": 0, "id": "68003", "errors": {"data.arrivalDate": ["The data.arrival date field is required."]}}]}

A successful request returns 200 with {"success": true, "message": "Created Successfully."}.

How to Get API Credentials

To obtain your API credentials, please email: support@bookingwhizz.com

PROFILES

API Endpoint

https://webhooks.bookingwhizz.com/{engine-name}/profiles


                    


                
                    <?php
                    $payload = '{ ... }'; // the JSON Request Sample below
                    $curl = curl_init();
                    curl_setopt_array($curl, array(
                    CURLOPT_URL => 'https://webhooks.bookingwhizz.com/{engine-name}/profiles',
                    CURLOPT_RETURNTRANSFER => true,
                    CURLOPT_ENCODING => '',
                    CURLOPT_MAXREDIRS => 10,
                    CURLOPT_TIMEOUT => 0,
                    CURLOPT_FOLLOWLOCATION => true,
                    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                    CURLOPT_CUSTOMREQUEST => 'POST',
                    CURLOPT_POSTFIELDS => $payload,
                    CURLOPT_HTTPHEADER => array(
                        'client-id: Test',
                        'password: 1234567',
                        'Content-Type: application/json'
                        ),
                    ));

                    $response = curl_exec($curl);

                    curl_close($curl);
                    echo $response;
                    ?>

Used to send guest details, preferences, and personal information.

POST call to the following url :
https://webhooks.bookingwhizz.com/{engine-name}/profiles 



Request example :
    {
    "id":"123",
    "accommodationId":"00512",
    "profileType":"1",
    "title":"Mr",
    "firstName":"John",
    "middleName":"",
    "lastName":"Smith",
    "gender":"1",
    "email":"test@gmail.com",
    "phoneNumber":"+1234567890",
    "languageCode":"eng",
    "nationality":"IND",
    "dateOfBirth":"1996-07-21",
    "placeOfBirth":"",
    "company":"",
    "notes":"",
    "address":"Street no 12, Delhi, India",
    "city":"Delhi",
    "postalCode":"123",
    "country":"India",
    "createdAt":"2026-10-05 07:36:53",
    "updatedAt":"2026-10-05 07:36:53"
    }
        

    Response:
            {
            "success": true,
            "message": "Created Successfully."
            }

HEADER

Field Type Description
client-id String (required) The client-id associated with the user. This is typically used for user authentication or account identification
password String (required) The user's password used for authentication. This field is required for post data

BODY

FIELD TYPE Req/Opt Description
id String Required The unique identifier for the Guests resource
accommodationId String Required Property code. Send as a string so leading zeros are kept (e.g. "00512").
profileType String Required Profile type: "1" = Guest, "2" = Company.
title String Optional One or more words used before the person's name. In some contexts it may signify veneration, an official position, or a professional or academic qualification.
firstName String Required The first name of the guest the resource is for.
middleName String Optional The middle name of the guest the resource is for.
lastName String Required The last name of the guest the resource is for.
gender String Optional Gender as per the ISO/IEC 5218 standard: 0 = not known, 1 = male, 2 = female, 9 = not applicable. Send 0 if the PMS has no value; do not send null.
email String Required Email addresses, the PMS has record of, for the guest in question.
phoneNumber String Required Telephone numbers, the PMS has record of, for the guest in question.
languageCode String Optional Language of the guest in ISO 639-3.
nationality String Required Nationality, the PMS has record of, for the guest in question in ISO 3166-1 alpha-3 format.
dateOfBirth String Optional Date of birth, the PMS has record of, for the guest in question in ISO-8601 format.
placeOfBirth String Optional Place of birth, the PMS has record of, for the guest in question.
company String Optional
notes String Optional A free text field for notes that the PMS holds on the guest in question.
address String Optional Addresses, the PMS has record of, for the guest in question.
city String Required City, the PMS has record of, for the guest
postalCode String Optional Postal Code, the PMS has record of, for the guest.
country String Required Country Name, the PMS has record of, for the guest in question in.
createdAt DateTime Required YYYY-MM-DD HH:mm:ss
updatedAt DateTime Required YYYY-MM-DD HH:mm:ss

BOOKING DATA


                    
     <?php
     $payload = '{ ... }'; // the JSON Request Sample below
     $curl = curl_init();
     curl_setopt_array($curl, array(
     CURLOPT_URL => 'https://webhooks.bookingwhizz.com/{engine-name}/bookings',
     CURLOPT_RETURNTRANSFER => true,
     CURLOPT_ENCODING => '',
     CURLOPT_MAXREDIRS => 10,
     CURLOPT_TIMEOUT => 0,
     CURLOPT_FOLLOWLOCATION => true,
     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
     CURLOPT_CUSTOMREQUEST => 'POST',
     CURLOPT_POSTFIELDS => $payload,
     CURLOPT_HTTPHEADER => array(
         'client-id: Test',
         'password: 1234567',
         'Content-Type: application/json'
         ),
     ));

    $response = curl_exec($curl);

     curl_close($curl);
     echo $response;
     ?>

Used to handle reservation details, source tracking, and market segmentation.

POST call to the following url :
https://webhooks.bookingwhizz.com/{engine-name}/bookings 



 Request Sample:
     {
        "accommodationId":"00512",
        "data":{
        "reservationId":"68003",
        "type":"BOOKING_CREATED",
        "externalReference":"",
        "arrivalDate":"2022-11-28",
        "departureDate":"2022-11-30",
        "arrivalTime":"10:00",
        "departureTime":"14:00",
        "status":"EXPECTED",
        "adultCount":1,
        "childCount":0,
        "roomQuantity":1,
        "marketCode":"COR",
        "marketDescription":"Corporate Negotiated Rates",
        "source":"HST",
        "sourceDescription":"Hotel Sales Team",
        "createdAt":"2026-10-05 07:36:53",
        "updatedAt":"2026-10-05 07:36:53",
        "roomDetails":[
        {
        "roomNumber":"527",
        "roomType":"EXK",
        "ratePlanType":"Bed & Breakfast",
        "rateCode":"BNB",
        "netAmount":100.00,
        "taxAmount":20.00,
        "grossAmount":120.00,
        "currencyCode":"USD",
        "guestProfile":[
        {
        "id":"123",
        "accommodationId":"00512",
        "profileType":"1",
        "title":"Mr",
        "firstName":"John",
        "middleName":"",
        "lastName":"Smith",
        "gender":"1",
        "email":"test@gmail.com",
        "phoneNumber":"+1234567890",
        "languageCode":"eng",
        "nationality":"IND",
        "dateOfBirth":"1996-07-21",
        "placeOfBirth":"",
        "company":"",
        "notes":"",
        "address":"Street no 12, Delhi, India",
        "city":"Delhi",
        "postalCode":"123",
        "country":"India",
        "createdAt":"2026-10-05 07:36:53",
        "updatedAt":"2026-10-05 07:36:53"
                                    }
                                ]
                            }
                        ]
                }
            }

            

    Response:
            {
            "success": true,
            "message": "Created Successfully."
            }

HEADER

Field Type Description
client-id String (required) The client-id associated with the user. This is typically used for user authentication or account identification
password String (required) The user's password used for authentication. This field is required for post data

BODY

FIELD TYPE Req/Opt DESCRIPTION
reservationId String Required This is the unique identifier for this booking. In most cases, hotel staff or guests won't know about or use this number.
reference String Optional The identifier hotel staff uses to look up the booking in their system. For guests who called in to make a booking (as opposed to booked through external channels like online travel agencies), this is the confirmation identifier they receive.
status String Required Booking Status (RESERVED, EXPECTED, CHECKED_IN, CHECKED_OUT, NO_SHOW, CANCELLED).
externalReferences String Optional References generated by external systems that the guest or booker might use for to identify the booking. This could be the confirmation number a online travel agency like Booking.com uses in their system, as opposed to the reference that is generated in the hotel system. As bookings are created through multiple systems, they might have multiple external references. As an example, a booking created by HRS through a Global Distribution System (GDS) might have a confirmation number generated by HRS as well as a GDS Personal Record Number.
ratePlanId String Optional Identifier of the rate plan in the PMS.
rateCode String Optional Rate code of the booking (e.g. BNB).
marketCode String Optional Used to identify the market segment this booking belongs to. Hotels often use this information to track performance in certain segments, e.g. business travel, individual guests or guests who stay through wholesale contracts. These values vary by hotel and aren't globally mapped.
source String Required Used by hotels to identify the source of business (e.g. mail, telephone, fax, central reservations, specific travel agencies like Booking.com or Expedia). These values vary by hotel and aren't globally mapped.
origin String Optional Typically used by hotels to identify the technical source of a Booking. These are often values like mail, telephone, fax, central reservations, travel agency or global distribution systems. These values vary by hotel and aren't globally mapped.
channelManager String Optional This field will be populated with the name of the channel manager that this booking was generated through. Channel manager software is used to distribute rates across channels (e.g. tens of online travel agencies) and limit availability to avoid overbooking.
arrivalDate String Required Date format (YYYY-MM-DD)
departureDate String Required Date format (YYYY-MM-DD)
arrivalTime String Optional Hours:Minutes
departureTime String Optional Hours:Minutes
areaId String Optional Room Id.
notes String Optional If guest has special request or any notes related to reservation.
requestedAreaTypeId String Optional Room type code the guest requested (e.g. EXK).
adultCount Integer Required
childCount Integer Optional
infantCount Integer Optional
roomDetails[].netAmount Float Optional Room price before tax, for this room.
roomDetails[].grossAmount Float Required Room price including tax, for this room.
roomDetails[].taxAmount Float Required Tax amount for this room.
roomDetails[].taxRate String Optional Tax rate applied to this room (e.g. "20" for 20%).
roomDetails[].currencyCode String Required Currency of this room's amounts, in ISO-4217 format (e.g. USD).
roomDetails[].guestProfile Array Required The guests staying in the room, one object per guest. A booking can have several rooms and a room can have several guests, so this is always an array. Every room needs at least one guest. The first guest in each room is that room's primary guest and must have an id. Each guest uses the fields described under PROFILES. The primary guest of the first room is treated as the booking's main guest.
allocationId String Optional Room Number
cancelledAt DateTime Optional Format: YYYY-MM-DD HH:mm:ss
createdAt DateTime Required Format: YYYY-MM-DD HH:mm:ss
updatedAt DateTime Required Format: YYYY-MM-DD HH:mm:ss

STAY DATA



    <?php
    $payload = '{ ... }'; // the JSON Request Sample below
    $curl = curl_init();
    curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://webhooks.bookingwhizz.com/{engine-name}/stays',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => array(
        'client-id: Test',
        'password: 1234567',
        'Content-Type: application/json'
        ),
    ));

    $response = curl_exec($curl);

    curl_close($curl);
    echo $response;
    ?>

Tracks room charges, payments, and stay revenue for loyalty programs and financial tracking.

POST call to the following url :
https://webhooks.bookingwhizz.com/{engine-name}/stays 


Request Sample:
    {
     "accommodationId":"00512",
     "data":{
     "reservationId":"68003",
     "type":"STAY_DATA",
     "externalReference":"",
     "arrivalDate":"2022-11-28",
     "departureDate":"2022-11-30",
     "status":"CHECKED_OUT",
     "adultCount":1,
     "childCount":0,
     "roomQuantity":0,
     "marketCode":"COR",
     "marketDescription":"Corporate Negotiated Rates",
     "source":"HST",
     "sourceDescription":"Hotel Sales Team",
     "origin":"CRS",
     "complimentary":"N",
     "notes":"Late checkout requested",
     "currencyCode":"USD",
     "totalRevenue":153.00,
     "roomRevenue":120.00,
     "fbRevenue":33.00,
     "otherRevenue":0.00,
     "createdAt":"2026-10-05 07:36:53",
     "updatedAt":"2026-10-05 07:36:53",
     "roomDetails":[
     {
     "roomNumber":"527",
     "roomType":"EXK",
     "ratePlanType":"Bed & Breakfast",
     "rateCode":"BNB",
     "netAmount":130.00,
     "taxAmount":23.00,
     "grossAmount":153.00,
     "charges":[
     {
     "id":"1352595",
     "billId":"68398",
     "netAmount":100.00,
     "taxAmount":20.00,
     "grossAmount":120.00,
     "currencyCode":"USD",
     "description":"TRF",
     "chargedAt":"2022-11-30 11:00:00",
     "notes":"ROOM TARIFF",
     "chargeCode":"ROOM"
     },
     {
     "id":"1352596",
     "billId":"68398",
     "netAmount":30.00,
     "taxAmount":3.00,
     "grossAmount":33.00,
     "currencyCode":"USD",
     "description":"TRF",
     "chargedAt":"2022-11-30 11:00:00",
     "notes":"F & B Revenue",
     "chargeCode":"FBREVENUE"
     }
     ],
     "payments":[
     {
     "id":"1355258",
     "billId":"68398",
     "amount":153.00,
     "currencyCode":"USD",
     "paymentMethod":"CRD",
     "paidAt":"2022-11-30 11:05:00",
     "notes":"CREDIT CARD"
     }
     ],
     "guestProfile":[
     {
     "id":"123",
     "accommodationId":"00512",
     "profileType":"1",
     "title":"Mr",
     "firstName":"John",
     "middleName":"",
     "lastName":"Smith",
     "gender":"1",
     "email":"test@gmail.com",
     "phoneNumber":"+1234567890",
     "languageCode":"eng",
     "nationality":"IND",
     "dateOfBirth":"1996-07-21",
     "placeOfBirth":"",
     "company":"",
     "notes":"",
     "address":"Street no 12, Delhi, India",
     "city":"Delhi",
     "postalCode":"123",
     "country":"India",
     "createdAt":"2026-10-05 07:36:53",
     "updatedAt":"2026-10-05 07:36:53"
                        }
                      ]
                    }
                 ]
             }
        }

            

     Response:
         {
         "success": true,
         "message": "Created Successfully."
         }

HEADER

Field Type Description
client-id String (required) The client-id associated with the user. This is typically used for user authentication or account identification
password String (required) The user's password used for authentication. This field is required for post data

BODY

FIELD TYPE Req/Opt DESCRIPTION
reservationId String Required The unique identifier of the stay. Use the same reservationId that was sent for this booking to the bookings endpoint.
complimentary String Optional Reservation is complimentary (Y/N).
status String Required Must be CHECKED_OUT. Stay data is sent once the guest has checked out.
rateCode String Optional Rate code of the booking (e.g. BNB).
marketCode String Optional Used to identify the market segment this booking belongs to. Hotels often use this information to track performance in certain segments, e.g. business travel, individual guests or guests who stay through wholesale contracts. These values vary by hotel and aren't globally mapped.
source String Optional Used by hotels to identify the source of business (e.g. mail, telephone, fax, central reservations, specific travel agencies like Booking.com or Expedia). These values vary by hotel and aren't globally mapped.
origin String Optional Typically used by hotels to identify the technical source of a Booking. These are often values like mail, telephone, fax, central reservations, travel agency or global distribution systems. These values vary by hotel and aren't globally mapped.
notes String Optional Free-text notes on the stay.
arrivalDate String Required Date format (YYYY-MM-DD).
departureDate String Required Date format (YYYY-MM-DD).
areaTypeId String Optional Room name of the booking.
chargedAt DateTime Optional When the charge was posted. Format: YYYY-MM-DD HH:mm:ss
totalRevenue Float Required Total revenue of reservation.
roomRevenue Float Required Total room revenue of reservation.
fbRevenue Float Required Total revenue of Food and Beverages.
otherRevenue Float Required Revenue not counted as room or F&B (e.g. spa, laundry). Send 0.00 if none.
currencyCode String Required Currency Code, the PMS has record of, for the guest in question in ISO-4217 format.
createdAt DateTime Required YYYY-MM-DD HH:mm:ss
updatedAt DateTime Required YYYY-MM-DD HH:mm:ss