Webhook

Overview

The Merchandising API Webhook is a real-time push notification service that alerts a Travel Buyer as soon as a hotel or room type is created or updated in Hotel Trader's inventory — without waiting for a scheduled pull.

The webhook payload itself is a lightweight notification, not the full record. It tells you which entity changed (by ID) and what kind of entity it is. Your system is expected to respond to the notification by calling GetPropertyData (for PROPERTY) or GetPropertyRoomData (for Room) with that ID to retrieve the full, current record — including mapping IDs (GIATA, Vervotech, or your own ID) already resolved.

This is what gives the webhook its speed advantage over polling: instead of waiting for your next scheduled full/incremental pull and diffing it yourself, you're told the instant a specific hotel changes and can fetch just that one record.

Requirements

To receive webhook notifications, your team must expose a publicly reachable HTTPS endpoint that:

• Accepts POST requests
• Accepts and returns application/json
• Returns a 2xx response promptly to acknowledge at the time of receipt

Payload Structure

Every webhook notification has two top-level objects: metadata and data.

{
  "metadata": {
    "entity": "PROPERTY",
    "entity_sub_type": "",
    "data_type": "NOTIFY"
  },
  "data": {
    "id": 8392
  }
}

metadata object

data object

The data object intentionally carries only the ID — not the full content — to keep the notification lightweight. Fetch the full record with the corresponding GraphQL query.

Entity Types

Data Types

Example Payloads

Property (hotel) notification

{
  "metadata": {
    "entity": "PROPERTY",
    "entity_sub_type": "",
    "data_type": "NOTIFY"
  },
  "data": {
    "id": 8392
  }
}

Recommended handling: on receipt, acknowledge with HTTP 2xx then call GetPropertyData filtered to propertyIds: [8392] to retrieve the full hotel record, including mappingProviders (GIATA / Vervotech / your own ID if enabled).

Room type notification

{
  "metadata": {
    "entity": "ROOM",
    "entity_sub_type": "",
    "data_type": "NOTIFY"
  },
  "data": {
    "id": 451123
  }
}

Recommended handling: on receipt,acknowledge with HTTP 2xx then call GetPropertyRoomData filtered to roomIds: [451123] to retrieve the full room record (occupancy rules, extra adult/child charges, room codes, description).

Recommended Integration Flow

1. Register/expose your webhook receiver endpoint with Hotel Trader
2. On each incoming POST, read metadata.entity to determine whether it's a PROPERTY or ROOM event.
3. Return a HTTP 2xx response to acknowledged the webhook was received.
4. Use data.id to call the matching GraphQL query (GetPropertyData or GetPropertyRoomData) and pull the current full record.
5. Update your internal system with the returned record.
6. Log/monitor for missed or failed deliveries

Why This Is Faster Than Polling

• No need to run scheduled full or incremental pulls and diff the results yourself to find what changed.
• No need to re-download a full content file to catch a handful of hotel updates.
• Mapping data (GIATA / Vervotech/Travel Buyer ID) is sourced directly from those providers, often ahead of their own API release, so a hotel notified via webhook can be mapped and actionable in your system faster than through the provider's native feed.