Run in production

Staying in sync

Don't re-crawl everything. Read the change feed or subscribe to webhooks, and refetch only what changed.

What to refetch

EventWhat to do
availability.changed, rates.changedRefresh that room type's dates.
property.updatedRefetch /properties/{code}.
reservation.*Your own bookings changed, including changes made at the property.

Public events (rates, availability, content, promotions and reviews) are visible to every partner. Reservation and group-request events are visible only to the partner that owns them.

Option 1: poll the change feed

GET /changes is an append-only, ordered feed of events.

1

Start from zero

Call GET /changes?since=0 and process the events in order.

2

Store the cursor

Save meta.next_cursor and pass it as since next time. Keep calling straight away while meta.has_more is true.

3

Poll every minute or two

Narrow the feed with types (for example availability.changed,rates.changed) or property. limit goes up to 500.

curl "https://api.konghotels.cloud/changes?since=0&types=availability.changed,rates.changed&limit=100" \
  -H "apikey: $KONG_HOTELS_API_KEY"

Option 2: subscribe to webhooks

Create a subscription with POST /webhooks, and we push the same event envelope used by /changes to your endpoint. Send a test event with POST /webhooks/{webhookId}/ping, and inspect attempts with GET /webhooks/{webhookId}/deliveries. GET /webhooks/event-types lists every event type.

Each delivery is a POST with these headers:

HeaderValue
Kong-EventThe event type
Kong-DeliveryA unique delivery ID. Use it to de-duplicate.
Kong-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>

Respond with any 2xx within 10 seconds. Failed deliveries are retried with backoff (30 s, 2 min, 10 min, 30 min, 1 h) before being marked failed.

Verify the signature

Compute HMAC_SHA256(secret, "<t>.<raw request body>") and compare it with v1 in constant time. Reject deliveries where t is more than 5 minutes old.

[$t, $v1] = sscanf($_SERVER['HTTP_KONG_SIGNATURE'], 't=%d,v1=%s');
$valid = hash_equals(hash_hmac('sha256', $t.'.'.file_get_contents('php://input'), $secret), $v1)
    && abs(time() - $t) < 300;
Rotating secrets

POST /webhooks/{webhookId}/rotate-secret issues a new signing secret. The secret is only returned when you create a subscription or rotate it, so store it straight away.