Skip to content

EventSubscription 1.2.0-rc.13

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:

  1. Read the raw request body as bytes, before any JSON parsing or re-encoding.
  2. Reject it if webhook-timestamp is more than 5 minutes away from your clock. This stops replayed requests.
  3. Build the signature as above and compare it in constant time with each space-separated entry of webhook-signature.
  4. 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"
  }
}

Servers: http://localhost:{port}/api/v2https://staging.hotelplatform.io/api/v2https://hotelplatform.io/api/v2

Subscription

Manage event subscriptions delivered via webhook or workflow.

List Subscriptions

GET /events/subscriptions

List registered event subscriptions.

Parameters

  • X-Tenant-Id (header, string, required)

    Tenant the request is made for. Subscriptions are scoped to this tenant.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Subscription

POST /events/subscriptions

Register a new event subscription. The eventType property discriminates the delivery mechanism: webhook posts the event to endpoint, workflow starts a workflow on the workflow server referenced by endpoint.

A webhook needs a secret. If it is created active, endpoint must first answer the signed verification request (see Endpoint verification); otherwise the request fails with 400 and nothing is saved.

Parameters

  • X-Tenant-Id (header, string, required)

    Tenant the request is made for. Subscriptions are scoped to this tenant.

Request body

application/vnd.api+json · Subscription

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Get Subscription

GET /events/subscriptions/{subscriptionId}

Get all information of a specified subscription.

Parameters

  • X-Tenant-Id (header, string, required)

    Tenant the request is made for. Subscriptions are scoped to this tenant.

  • subscriptionId (path, string, required)

    Id of the subscription

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Subscription

PUT /events/subscriptions/{subscriptionId}

Update the subscription. endpoint, events and active are replaced (active defaults to true when omitted). eventType cannot be changed: delete the subscription and create a new one instead. For a webhook, omitting secret keeps the current one and sending one rotates it; omitting dataRequired keeps the current value. secret and dataRequired are rejected with 400 for other subscription types.

Every update that leaves a webhook active verifies the endpoint again with the endpoint and secret in the request (see Endpoint verification). If that fails, the request fails with 400, nothing in it is applied, the webhook is deactivated and the reason is recorded in failureReason. A successful check clears failingSince and failureReason.

Parameters

  • X-Tenant-Id (header, string, required)

    Tenant the request is made for. Subscriptions are scoped to this tenant.

  • subscriptionId (path, string, required)

    Id of the subscription

Request body

application/vnd.api+json · Subscription

Responses

  • 204

    No Content

Delete Subscription

DELETE /events/subscriptions/{subscriptionId}

Remove the subscription.

Parameters

  • X-Tenant-Id (header, string, required)

    Tenant the request is made for. Subscriptions are scoped to this tenant.

  • subscriptionId (path, string, required)

    Id of the subscription

Responses

  • 204

    No Content