HotelPlatform delivers information about events to subscribers. Register an
event subscription to receive the events you are interested in.
A subscription selects a delivery mechanism via its eventType:
webhook — the event is POSTed to your endpoint.
workflow — the event triggers a workflow on your workflow server.
Alternatively you can connect to the websocket to receive events in real-time.
A webhook endpoint must be an absolute http or https URL. A webhook whose deliveries
keep failing is deactivated automatically (see Delivery).
Webhook security
Requests to your endpoint are signed as specified by
Standard Webhooks, so any Standard Webhooks
library can verify them.
Every webhook subscription has a secret that you create: whsec_ followed by the
base64 encoding of 24-64 random bytes (e.g. "whsec_" + base64(32 random bytes)). A key
that is obviously not random (fewer than 8 different byte values) is rejected with 400.
It is write-only: responses show REDACTED instead of the value.
Every request carries these headers:
webhook-id: message id. For events it is the CloudEvent id, so you can use it to
drop duplicates. The verification request gets a new random id every time.
webhook-timestamp: when the request was signed, in Unix seconds.
webhook-signature: v1, followed by the base64 signature. Missing only for a
webhook without a secret (see Webhooks without a secret).
X-Webhook-Event: the event type (webhook.verification for the verification
request). Not part of Standard Webhooks.
The signature is built like this:
key = base64-decode( secret without the "whsec_" prefix )
signed content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature = "v1," + base64( HMAC-SHA256( key, signed content ) )
To check a request:
- Read the raw request body as bytes, before any JSON parsing or re-encoding.
- Reject it if
webhook-timestamp is more than 5 minutes away from your clock. This
stops replayed requests.
- Build the signature as above and compare it in constant time with each
space-separated entry of
webhook-signature.
- Reject the request with
401 if no entry matches.
Webhooks without a secret
A webhook created before signing existed has no secret (secret: null in responses).
Its deliveries carry webhook-id, webhook-timestamp and X-Webhook-Event, but no
webhook-signature, so the receiver cannot tell them from forged requests. Set a
secret with an update to have its requests signed from then on; the update verifies
the endpoint with a signed request first (see Endpoint verification). Every webhook
created now has a secret, and verification requests are always signed.
Endpoint verification
Before a webhook becomes active (on create with active: true and on every update that
leaves it active), the service sends a signed verification request (see the
endpointVerification webhook) with a random challenge. Your endpoint must check the
signature and answer within 10 seconds with a 2xx status and the JSON body
{"challenge": "<the same value>"}. If it does not, the request is rejected with 400:
on create nothing is saved, on update nothing in the request is applied and the
webhook is deactivated.
Delivery
Each event is sent once per matching active webhook (see the subscriptionEvent
webhook); there are no retries. Your endpoint must answer within 10 seconds with any 2xx status; the
response body is ignored. A non-2xx status, no answer in time or a connection error
counts as a failed delivery and is shown in failingSince and failureReason. The
next successful delivery clears both. A webhook that keeps failing for 120 minutes is deactivated
automatically. Updating it with active: true verifies the endpoint again and
reactivates it.
Events
Every event is a CloudEvent:
type says what happened: io.hotelplatform.<domain>.<resource>.<action>, e.g.
io.hotelplatform.payment.intent.created. It is complete on its own; filter on it.
Its last two segments are the event name you subscribe to (intentCreated).
source is the domain the event comes from: io.hotelplatform.<domain>, e.g.
io.hotelplatform.payment.
subject is the resource the event is about: <resource>/<id>, e.g.
intent/90a6427b-6f4c-4b1e-9d64-2d4f8f0b1c3a.
What a webhook receives depends on its dataRequired:
false (default): only the event metadata and a reference to the resource
(WebhookEventMetadata, application/vnd.api+json). Fetch the resource with its GET
operation for the details.
true: the full CloudEvent including data as published (WebhookCloudEvent,
application/cloudevents+json).
Example (dataRequired: false)
{
"eventId": "4833d1ec-0ee6-47bf-bbb0-871fedae6659",
"eventType": "io.hotelplatform.payment.intent.created",
"source": "io.hotelplatform.payment",
"time": "2026-09-15T08:30:00+00:00",
"data": {
"type": "intent",
"id": "90a6427b-6f4c-4b1e-9d64-2d4f8f0b1c3a"
}
}