Webhooks Usage Guide

The Open API platform delivers business events to applications through webhooks. Configure one public HTTPS endpoint for an application. All event types are delivered to that endpoint, and the eventType field determines the structure of payload.

Integration flow

Configure and enable a public HTTPS webhook URL.
Accept POST requests and parse payload according to eventType.
Use eventId as the idempotency key.
Return any HTTP 2xx response after accepting the event.

Event envelope

Every event contains the following fields:

Field	Type	Description
`eventId`	string	Unique event identifier for idempotent processing
`eventType`	string	Event type that identifies the payload schema
`occurredAt`	string	Event occurrence time in ISO 8601 format
`hotelId`	string	Hotel identifier
`payload`	object	Event data defined by `eventType`

Event types

`im.message.created`

Indicates that a message was created. The event uses the message-created payload schema.

`im.message.updated`

Indicates that a message changed. A delivery-status change is one type of message update.

When sender equals the calling application's appCode (client_id), the message was sent by that application. Other values may identify a PMS operator or guest.

See the Webhooks API Reference for complete payload fields, enum values, and schemas.

Delivery and retries

Any HTTP 2xx response indicates successful delivery. A non-2xx response, timeout, DNS failure, TLS failure, or connection failure is treated as unsuccessful. Delivery is retried up to three times and does not follow HTTP 3xx redirects.

The same event may be delivered more than once. Consumers should use eventId to process events idempotently.

Security

When a callback token is configured together with the webhook URL in the Open API platform, Webhook requests include that value in the optional token header. Validate the token when your application configures one. This callback token authenticates outbound webhook delivery only and cannot be used as the Bearer credential for inbound Open API requests.

Store a configured callback token as a secret, avoid logging it, and rotate it if it is exposed. The callback URL must use public HTTPS and must not resolve to localhost, private, link-local, or other non-public addresses.