Payload Versions

Description of the Web hook payload versions

Payload Versions

Zaui supports versioned webhook payloads so existing integrations can remain stable while newer integrations adopt an updated schema and additional data fields.

Each webhook can be configured to send a specific payload version. This allows existing consumers to remain on the legacy payload while new or updated integrations move to the modernized structure.

---

Available Versions

2016-04-10

Legacy webhook payload format.

Use this version if your current integration depends on the original payload structure and formatting.

2026-04-10

Current webhook payload format.

Use this version for new integrations or when updating an existing integration to the modernized schema. This version introduces structural, type, and field-level changes, including pass-related payload support and additional booking, activity, and transaction attributes.

---

How Version Selection Works

Webhook payload versioning is configured per webhook record.

When creating or editing a webhook in Zaui, you can choose which payload version that webhook should send:

• A webhook set to 2016-04-10 continues to receive the legacy payload shape.

• A webhook set to 2026-04-10 receives the updated payload shape and field set.

The delivered payload includes eventNotificationApiVersion, which identifies the version used for that webhook event.

---

Which Version Should I Use?

Use 2026-04-10 for all new integrations.

If you already consume Zaui webhooks in production and your parser depends on the legacy structure, remain on 2016-04-10 until you have tested and updated your integration for the new schema.

---

What Changed in 2026-04-10

The 2026-04-10 payload modernizes the webhook schema in several important ways:

• collections are emitted as JSON arrays

• numeric fields are emitted as native numbers

• boolean fields are emitted as native booleans

• date-time fields use ISO 8601 with timezone offset

• missing scalar values use null

• additional booking, activity, and transaction fields are included

• pass sales and pass usage data are supported

These changes improve consistency, reduce parsing complexity, and make the payload easier to consume in modern systems.

---

Key Differences Between Versions

Collections

Legacy payloads may wrap collections as objects. The modern payload uses arrays consistently.

Legacy:

"customers": {
  "customer": {
    "customerId": "1614"
  }
}

Current:

"customers": [
  {
    "customerId": 93
  }
]

This same pattern applies to sections such as activities, products, giftCertificates, and transactions.

Numbers

Legacy payloads often emit numeric values as strings. The modern payload emits native numbers.

Legacy:

"eventNotificationTypeId": "100",
"amount": "42.900000"

Current:

"eventNotificationTypeId": 100,
"amount": 7840

Booleans

Legacy payloads may emit booleans as strings. The modern payload emits booleans directly.

Legacy:

"isBookingCancelled": "false"

Current:

"isBookingCancelled": false

Date and Time Formatting

Legacy payloads use mixed and inconsistent date formats. The modern payload uses ISO 8601 with timezone offset.

Legacy:

"eventNotificationDateTime": "2026-02-16 13:13:08",
"activityDate": "Thursday February 19 2026"

Current:

"eventNotificationDateTime": "2026-04-10T14:16:59-07:00",
"activityDate": "2026-04-09T00:00:00-07:00"

Null and Empty Values

Legacy payloads may use empty objects or empty strings inconsistently. The modern payload uses null for missing scalar values where appropriate.

Legacy:

"addressLine1": {},
"activityNotes": {}

Current:

"addressLine1": null,
"activityNotes": null

---

Event Envelope

The event envelope in 2026-04-10 includes standard event metadata plus the selected payload version.

Example

{
  "eventNotificationUniqueId": "evt_5d64823a3422fe2d7cecf93d5818526743efeb18",
  "eventNotificationCompanyName": "Aurorasky ",
  "eventNotificationCompanyIdentifier": "b6589fc6ab",
  "eventNotificationGroupId": 100,
  "eventNotificationTypeId": 100,
  "eventNotificationType": "booking.creation",
  "eventNotificationDateTime": "2026-04-10T14:16:59-07:00",
  "eventNotificationName": "Booking Test",
  "eventNotificationSystem": "suppliertestsystem",
  "eventNotificationSystemUrl": "https://suppliertestsystem.zaui.net/",
  "eventNotificationApiVersion": "2026-04-10",
  "eventNotificationTypeV2": "booking.creation"
}

Notable Envelope Fields

Field	Description
eventNotificationGroupId	Event group identifier
eventNotificationTypeId	Event type identifier
eventNotificationType	Event name
eventNotificationTypeV2	Normalized event type string
eventNotificationDateTime	Timestamp of the event in ISO 8601 format
eventNotificationApiVersion	Payload version selected on the webhook
eventNotificationName	Webhook name
eventNotificationSystem	Source system name
eventNotificationSystemUrl	Source system URL

---

Booking Object

The booking object in 2026-04-10 includes both structural improvements and additional fields.

Example

"booking": {
  "bookingId": 693,
  "isBookingCancelled": false,
  "bookingReference": "XKZFSBR",
  "bookingSaleDateTime": "2026-04-09T13:11:20-07:00",
  "bookingCloseDateTime": "2026-04-09T00:00:00-07:00",
  "bookingRef": "XKZFSBR",
  "agentRef": null
}

Booking Fields

Field	Description
bookingId	Booking identifier
isBookingCancelled	Indicates whether the booking is cancelled
bookingReference	Booking reference value emitted in the current payload
bookingRef	Customer-facing booking reference
agentRef	Optional reseller-supplied reference
bookingSaleDateTime	Booking sale date and time
bookingCloseDateTime	Booking close date and time

Notes

• agentRef is populated from tbooking.referenceId for agent/OTA bookings. For direct bookings (or when referenceId is not present), the value is null.

• Both bookingReference and bookingRef may be present in the current payload.

---

Booking Revenue

The bookingRevenue structure in 2026-04-10 uses native numeric values.

Example

"bookingRevenue": {
  "bookingSubTotal": 6000,
  "bookingTax": 1839,
  "bookingTotal": 7840
}

Consumers should treat these values as numbers, not strings.

---

Customer Data

Customer records are emitted as array items in the current version and use typed values consistently.

Example

"customers": [
  {
    "customerId": 93,
    "firstName": "Nad",
    "lastName": "Dau",
    "birthDate": "2006-02-23",
    "homePhone": null,
    "mobilePhone": "6404563125",
    "email": "[e-mail]",
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "state": null,
    "zipCode": null,
    "country": "Canada",
    "username": "[e-mail]",
    "newsLetterOptIn": false,
    "loyaltyProgramOptIn": false,
    "allowsPrivateDataSharing": false
  }
]

---

Activity Object

In 2026-04-10, activity payloads include modernized typing as well as additional contextual fields.

Example

{
  "activityId": 2,
  "activityType": "Regular",
  "activityName": "The Rings of Saturn",
  "activityDate": "2026-04-09T00:00:00-07:00",
  "activityTime": "09:00:00",
  "activityDescription": "Fun facts about Saturn...",
  "activityDuration": "5:00:00"
}

Activity Fields

Field	Description
activityId	Activity identifier
activityType	Activity type
activityName	Activity name
activityDate	Activity date in ISO 8601 format
activityTime	Activity time
activityDescription	Descriptive context for the booked activity instance
activityDuration	Duration of the activity in HH:MM:SS format

Notes

For point-to-point activities, activityDescription may represent the actual passenger journey segment rather than the full route.

For point-to-point activities, activityDuration may reflect the time between departure and arrival stops.

---

Transaction Object

The transactions array in 2026-04-10 contains modernized transaction records and supports pass usage data.

Example

{
  "id": 830,
  "attributeId": 830,
  "purchaseType": 3000,
  "transactionType": 2042,
  "transactionName": "Pass",
  "transactionTypeLedgerEntry": "N/A",
  "amount": 7840,
  "dateCreated": "2026-04-09T13:11:20-07:00",
  "productId": 0,
  "productDate": null,
  "activityId": 0,
  "activityDateTime": null,
  "resellerCompanyId": 0,
  "resellerCompanyName": null,
  "resellerInvoiceNumber": null,
  "resellerRateName": null,
  "resellerRate": 0,
  "resellerNet": 0,
  "discountRate": 0,
  "promoCodeName": null,
  "promoCodeRate": 0,
  "promoCodeRateType": null,
  "resellerBusinessNumber": null
}

Transaction Fields

Field	Description
id	Transaction identifier
attributeId	Transaction attribute identifier
purchaseType	Purchase type identifier
transactionType	Transaction type identifier
transactionName	Transaction type name
transactionTypeLedgerEntry	Ledger entry classification
amount	Transaction amount
dateCreated	Transaction creation timestamp
productId	Related product identifier
productDate	Related product date
activityId	Related activity identifier
activityDateTime	Related activity date-time
resellerCompanyId	Reseller company identifier
resellerCompanyName	Reseller company name
resellerInvoiceNumber	Reseller invoice number
resellerRateName	Reseller rate name
resellerRate	Reseller rate value
resellerNet	Reseller net value
discountRate	Discount rate
promoCodeName	Promo code name
promoCodeRate	Promo code rate
promoCodeRateType	Promo code rate type
resellerBusinessNumber	Reseller business number
passUsage	Nested pass usage object when applicable

Important Note

Do not assume transactionReference and merchantRef are currently available in 2026-04-10.

For standard payment transactions (for example, credit card and cash payments), both lineItemId and packageId are returned as null. These fields are only populated where item-level transaction context applies.

Earlier source material identified them as planned, and the validated live payload used for documentation does not include them. Until explicitly confirmed in a live implementation, integrations should not treat them as guaranteed fields.

---

Pass Data

The 2026-04-10 payload supports pass-related information for bookings and transactions.

Top-Level Pass Support

The booking payload can include:

• passes

• pass-related transaction information

• pass usage details on relevant transactions

Example Empty State

"passes": []

When a booking includes pass sales, the passes array may contain pass details such as pass metadata, pricing, validity, and usage-related values.

---

Pass Usage on Transactions

In the current live 2026-04-10 implementation, pass usage is represented as a nested passUsage object on the transaction.

Example

"passUsage": {
  "passId": 7,
  "redemptionCode": "XK856LY",
  "usageType": "1",
  "unitsUsed": 1,
  "passName": "5 Trips",
  "passBalanceRemaining": 0,
  "transactionId": 830,
  "itemType": "activity",
  "itemId": 2,
  "itemName": "The Rings of Saturn",
  "amount": 7840,
  "redeemedOn": "2026-04-09T13:11:20-07:00"
}

Pass Usage Fields

Field	Description
passId	Pass identifier
redemptionCode	Pass redemption code
usageType	Pass usage type
unitsUsed	Amount of pass value or units used
passName	Pass name
passBalanceRemaining	Remaining balance after redemption
transactionId	Related transaction identifier
itemType	Redeemed item type
itemId	Redeemed item identifier
itemName	Redeemed item name
amount	Amount associated with the redemption
redeemedOn	Redemption timestamp

---

Breaking Changes to Consider Before Migrating

Switching a webhook from 2016-04-10 to 2026-04-10 may require parser changes.

Before switching versions, confirm that your integration can handle:

• arrays instead of object-wrapped collections

• numbers instead of numeric strings

• booleans instead of string booleans

• ISO 8601 date-time values with timezone offsets

• null values for optional scalar fields

• additional booking, activity, and transaction fields

• pass-related payload sections when applicable

---

Migration Checklist

Before enabling 2026-04-10 on an existing webhook:

1. Update your parser to support array-based collections.

2. Update type handling for numbers and booleans.

3. Update date parsing for ISO 8601 with timezone offsets.

4. Update null-handling for optional values.

5. Validate any reconciliation logic that depends on transaction fields.

6. Test pass purchases and pass redemptions if your implementation uses passes.

7. Review the live payload output in a test environment before switching production endpoints.

---

Recommended Best Practice

For new webhook integrations, use 2026-04-10.

For existing consumers of the legacy webhook format, migrate only after validating payload parsing and downstream processing against the modernized schema.

---

FAQ

What should the API Version field be set to?

Use 2026-04-10 for new integrations. Keep 2016-04-10 only for backward compatibility where an existing parser still depends on the legacy schema.

Is the version configured globally?

No. Versioning is selected per webhook record.

Does 2026-04-10 include pass-related data?

Yes. The current payload supports pass data and nested passUsage on transactions where applicable.

Are transactionReference and merchantRef available in 2026-04-10?

Do not assume they are currently available. They are not present in the validated live example used for this documentation.

Where should the API Version help link in the UI point?

It should point to this page: /webhooks/payload-versions