Getting Started

Getting started using Zaui Webhooks and sending them to your endpoints.

Webhook notifications sent from a Zaui supplier system are sent over standard HTTPS POST request as JSON or XML.

Your server must respond with a HTTP 200 class status code immediately upon receipt. If your server does not indicate a successful response in a timely manner, or after 5 consecutive failed delivery attempts, your we

Within the Zaui supplier system, Webhook setup can be found in the Settings > Webhooks section of the Zaui system.

Event Overview

Zaui generates event data that we can send you to inform you of an event that occurred on the platform.

When an event occurs, Zaui generates a new Event Object. For example, if a new booking was created on the platform from the booking engine, or through an OTA channel, you receive a Booking Create event.

By registering webhook endpoints in your Zaui platform, you enable Zaui to automatically send Event Objects as part of the POST request to the registered webhook endpoint hosted by your application. After your webhook endpoint receives the Event, your app can run backend actions (for example adding booking revenue into your financial system, or other operational tasks associated with the event.

Event Object

The Event object we send to your webhook endpoint provides a snapshot of the object associated with the event on the platform.

See a full list of event types that we send your webhook.

How to Create a Webhook

1. On your Zaui system, login and navigate to Settings > Webhooks

2. In the left sidebar, click Create

3. Provide a name for the webhook, if its enabled, the Endpoint URL and type of webhook to be triggered (see a list of all available payload types)

4. Delivery type can be XML or JSON

5. Click Save

How to configure a webhook in Zaui

This process sets up an individual endpoint for a specific event.

Create your Endpoint Handler

Setup your HTTPS endpoint function that can accept webhook requests with a POST method.

Setup your endpoint function so that it:

1. Handles POST requests with a JSON payload which handles the inbound Event object.

2. Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, your must return a 200 response before updating your CRM system when a new customer purchases on your Zaui system.

Secure your endpoint

We highly recommend that you secure your integration by ensuring your handler verifies that all webhook requests are generated by Zaui. You will need to verify these manually.

Verify webhook signatures manually

The Zaui-Signature header included in each signed event contains the timestamp and a signature that you must verify. The timestamp is prefixed by t=, and the signature prefixed by v=

Zaui-Signature:
t=1714062844,
v=8e584e4da112d941f7f20b2d2d5667b4619c043577af74f4105111aab180f1a9

We provide newlines for clarity, but a real Zaui-Signature header is on a single line.

Zaui generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

To create a manual verification you must complete the following steps:

Step 1: Extract the timestamp and signatures from the header

Split the header into corresponding timestamp (t) and signature (v). You can discard all other elements.

Step 2: Prepare the signed payload string

The signed payload string is created by concatenating:

• The timestamp (as a string)

• The character .

• The actual JSON payload (that is the request body)

Step 3: Determine the expected signature

Compute the HMAC with the SHA256 hash function. Use the endpoints signing secret as the key, and use the signed payload string as the message.

The secret is available from within the webhook setup in your Zaui system.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time-string comparison to compare the expected signature to the received signature.

Best practices for using webhooks

Review these best practices to make sure your webhooks remain secure and function well with your integration.

Quickly return a 2xx response

Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout.

Handle Duplicate Events

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicate events by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already logged events. The eventNotificationUniqueId makes this possible.

Only listen to event types your integration requires

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra (or all events) puts undue strain on your server and we don't recommend it.

Handle events asynchronously

Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously.

Prevent replay attacks

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Zaui includes a timestamp in the Zaui-Signature header. Because this timestamp is part of the signed payload, it also verified by the signature, so an attacker can't change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

For example, a default tolerance of 5 minutes between the timestamp and the current time could be used, your endpoint would capture the timestamp from the headers and verify the time stamp is within in the tolerance parameters.

$tolerance = 300; // 5 minutes in seconds
$current_time = time();

if (abs($current_time - (int)$header_timestamp) > $tolerance) {
    //do something to handle the difference
}