Webhook Integration

Push reservation events to Hotelinking in real-time as they happen.

How It Works

Instead of Hotelinking pulling data from your API, you push events to a dedicated webhook endpoint whenever a reservation is created, updated, or cancelled.

Receive a unique webhook URL

Hotelinking provides a unique webhook URL for each brand integration. All events for that brand are sent to this single endpoint.

Send HTTP POST requests

Your system sends a POST request to the webhook URL whenever a reservation event occurs. Include the event type, timestamp, and full reservation data in the payload.

Validate and process

Hotelinking validates the payload signature, then processes the data through the same normalization and transformation process used by REST API integrations.

Deliver to destination

Processed records are delivered to the configured destination system in real-time, without waiting for a scheduled sync.

Setting Up Webhooks

Webhook endpoints are provisioned during onboarding. Your Hotelinking contact will provide you with:

What you will receive

Provided during integration onboarding

A unique webhook URL for each brand integration
A webhook secret for signing request payloads
Configure these in your system, then send a test event to verify the connection

Event Types

Each webhook payload includes an event type that describes what happened.

reservation.created

A new reservation has been received. Send when a booking is first confirmed in your system.

reservation.updated

An existing reservation has been modified. This covers date changes, status transitions, room upgrades, or guest detail updates.

reservation.cancelled

A reservation has been cancelled or marked as a no-show. Include the final status in the payload.

guest.updated

Guest profile information has changed outside the context of a specific reservation (e.g. email update, loyalty enrollment).

Payload Format

All webhook payloads follow a consistent structure with the event type, timestamp, brand identifier, and the full event data.

json

{
  "event": "reservation.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "brand_id": "your-property-id",
  "data": {
    "reservation_id": "RES-001",
    "confirmation_number": "CONF-123",
    "check_in": "2026-02-01",
    "check_out": "2026-02-05",
    "status": "confirmed",
    "guests": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+34612345678"
      }
    ],
    "stays": [
      {
        "room_type": "Double",
        "board_type": "HB",
        "adults": 2,
        "children": 0
      }
    ]
  }
}

Include all available data

Send the complete reservation object in every event, not just the changed fields. This ensures Hotelinking always has the latest state without needing follow-up API calls.

Required Headers

Every webhook request must include the following headers for authentication and validation.

POSThttps://integrations.hotelinking.com/webhooks/{endpoint_id}

Content-Type (required) — application/json
X-Webhook-Signature (required) — HMAC-SHA512 signature of the request body
X-Webhook-Timestamp (required) — Unix timestamp (seconds) when the request was sent

headers

POST https://integrations.hotelinking.com/webhooks/{endpoint_id}
Content-Type: application/json
X-Webhook-Signature: sha512=a1b2c3d4e5f6...
X-Webhook-Timestamp: 1706000000

Signature Verification

Hotelinking verifies every incoming webhook using HMAC-SHA512 signatures to ensure the payload has not been tampered with and originates from your system.

Construct the signing string

Concatenate the timestamp and raw request body, separated by a period: timestamp.body

Compute the HMAC

Sign the string using HMAC-SHA512 with your webhook secret as the key.

Send as header

Include the hex-encoded signature in the X-Webhook-Signature header, prefixed with sha512=.

pseudocode

timestamp = current_unix_timestamp()
body      = json_encode(payload)
signature = hmac_sha512(webhook_secret, timestamp + "." + body)

headers = {
  "Content-Type":        "application/json",
  "X-Webhook-Signature": "sha512=" + hex_encode(signature),
  "X-Webhook-Timestamp": timestamp
}

Replay protection

Hotelinking rejects requests with timestamps older than 5 minutes. Ensure your system clock is synchronized (NTP) and the X-Webhook-Timestamp reflects the actual send time.

Retry Behavior

If Hotelinking returns a non-2xx response, your system should retry the request with exponential backoff.

Retry schedule

Exponential backoff with 4 retries

First retry

After 1 minute

Second retry

After 5 minutes

Third retry

After 30 minutes

Final retry

After 2 hours

Dead letter queue

After 4 failed attempts, the event is moved to a dead letter queue for manual inspection. Failed events can be replayed once the underlying issue is resolved.

Best Practices

Send events in real-time

Push events as close to real-time as possible. Batching events into periodic dumps defeats the purpose of webhooks and delays guest communication.

Include complete data

Send the full reservation object in every event, including all guest, stay, and charge data. Partial payloads require additional API lookups and increase latency.

Use idempotent event IDs

Include a unique event ID in each payload so that duplicate deliveries (from retries) can be safely deduplicated on the receiving end.

Test in sandbox first

Use the sandbox environment to validate your webhook implementation before routing production events. Sandbox endpoints accept any payload without affecting live data.