Order status callback

Overview

The Order Callback service provides real-time notifications when your order status changes. Instead of polling for order status updates, you can receive automatic webhook callbacks when important events occur.

How It Works

Callback Mechanism

Registration: Provide your callback URL when creating an order via the Book API

Event Trigger: When an order status changes (e.g., payment completed, order cancelled), our system automatically triggers a callback

Async Delivery: Callbacks are sent asynchronously to avoid blocking order processing

Retry on Failure: If delivery fails, the system automatically retries with exponential backoff

Idempotent: Due to occasional network issues or other factors, the order status push event may be inconsistent with the normal state transition. This is unavoidable, so you need to handle idempotency on your side

Integration Steps

Step 1: Implement Your Callback Endpoint

Create an HTTPS endpoint that can receive POST requests with JSON payloads.

Requirements:

Must be publicly accessible

Must support HTTPS

Must return HTTP 2xx status codes on success

Should process callbacks asynchronously

Example Implementation:

Step 2: Configure Callback URL in Book Request

When calling the Book API, include your callback URL in the request:

{
  "customerReferenceNo": "REF123456",
  "ratePkgId": "pkg_123456",
  "holder": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  },
  "guests": [
    {
      "roomIndex": 1,
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
  "callbackUrl": "https://your-domain.com/webhook/order-callback"
}

Important Notes:

callbackUrl is optional

Must be a valid HTTPS URL

The same URL will be used for all events related to that order

URL is stored with the order and used for all subsequent callbacks

Step 3: Handle Callback Events

Your callback endpoint will receive notifications for the following events:

Event	Description	When Triggered
`order_created`	Order created but not yet paid	After successful order creation
`order_paid`	Order payment completed	After payment is confirmed
`order_cancelled`	Order cancelled	After order is cancelled

Note: Additional events (order_confirmed, order_updated, order_checkedin, order_checkedout) are planned but not yet supported.

Each callback contains the following JSON payload:

{
  "customerReferenceNo": "REF123456",
  "hotelConfirmNo": "HCN789012",
  "event": "order_paid",
  "eventTime": 1704067200000
}

Payload Fields:

Field	Type	Description	Example
`customerReferenceNo`	string	Your order reference number	`REF123456`
`hotelConfirmNo`	string	Hotel confirmation number (may be empty for some events)	`HCN789012`
`event`	string	Event type	`order_paid`
`eventTime`	int64	Event timestamp in Unix milliseconds	`1704067200000`

Request Headers:

Content-Type: application/json
User-Agent: hotel-be-webhook/1.0

Order status callback

Overview#

How It Works#

Callback Mechanism#

Integration Steps#

Step 1: Implement Your Callback Endpoint#

Step 2: Configure Callback URL in Book Request#