Webhooks

CheckYout sends a signed webhook to your configured endpoint on every guest check-out. The full reference is below.

Overview

Property	Value
HTTP method	POST
Content-Type	`application/json`
Target URL	Your configured webhook URL
Trigger	Guest taps the checkout sign
Rate limit	Max 1 checkout per device per minute

Webhook secret strongly recommended

We strongly recommend configuring a webhook secret. Without signature verification, third parties could send forged webhook events to your endpoint. See Authentication for details.

Headers

Header	Description
`Content-Type`	`application/json` — always present
`X-CheckYout-Signature`	HMAC-SHA256 hex digest — only present when a webhook secret is configured

Payload schema

Field	Type	Required	Description
`event_id`	`string`	Yes	Unique UUID of the event. Use it for deduplication.
`event`	`string`	Yes	Event type, currently always `"checkout"`
`device_id`	`string`	Yes	UUID of the CheckYout device (sign)
`property_name`	`string`	Yes	Property name (or device ID as fallback)
`property_city`	`string \| null`	No	Property city if set
`timestamp`	`string`	Yes	ISO 8601 timestamp of the checkout event
`source`	`string`	Yes	Always `"checkyout"`

Example payload

{
  "event_id": "a7c3f1e2-9b4d-4e8a-b6c5-d2f1a3e4b5c6",
  "event": "checkout",
  "device_id": "d4f8a2b1-3c5e-4f6a-8b9c-1d2e3f4a5b6c",
  "property_name": "Alpenblick Vacation Rental",
  "property_city": "Interlaken",
  "timestamp": "2026-04-11T14:32:00.000Z",
  "source": "checkyout"
}

Signature verification

The signature is the HMAC-SHA256 hash of the JSON body with your webhook secret, encoded as a hex string. Code examples are under Authentication → Verify the signature.

Retry behaviour

On a failed delivery (non-2xx response, timeout or network error), CheckYout retries the webhook automatically with exponential backoff:

Attempt	Delay
1st attempt	Immediate
2nd attempt	After 1 minute
3rd attempt	After 5 minutes

Client errors (4xx other than 429) are not retried — those signal a problem with your configuration.

Timeout

Respond within 10 seconds with a 2xx status code. We recommend processing the event asynchronously and replying immediately with 200 OK.

Idempotency

Every event carries a unique event_id (UUID). Use it for deduplication if a retry causes the same event to be delivered more than once.

Recommendations

Always reply with 200 OK and process the event asynchronously.
Verify the signature before processing.
Persist the event before responding 200, so you do not lose data.
Implement client-side idempotency on device_id + timestamp.

Next: Notify API reference