Webhooks

CheckYout sendet bei jedem Gast-Checkout einen signierten Webhook an Ihren konfigurierten Endpoint. Hier finden Sie die vollständige Referenz.

Übersicht

Eigenschaft	Wert
HTTP-Methode	POST
Content-Type	`application/json`
Ziel-URL	Ihre konfigurierte Webhook-URL
Auslöser	Gast tippt das Checkout-Sign an
Rate-Limit	Max. 1 Checkout pro Gerät pro Minute

Webhook-Secret dringend empfohlen

Wir empfehlen dringend, ein Webhook-Secret zu konfigurieren. Ohne Signaturverifizierung können unbefugte Dritte gefälschte Webhook-Events an Ihren Endpoint senden. Details unter Authentifizierung.

Headers

Header	Beschreibung
`Content-Type`	`application/json` — immer vorhanden
`X-CheckYout-Signature`	HMAC-SHA256 Hex-Digest — nur vorhanden, wenn ein Webhook-Secret konfiguriert ist

Payload-Schema

Feld	Typ	Pflicht	Beschreibung
`event_id`	`string`	Ja	Eindeutige UUID des Events. Verwenden Sie diese zur Deduplizierung.
`event`	`string`	Ja	Event-Typ, aktuell immer `"checkout"`
`device_id`	`string`	Ja	UUID des CheckYout-Geräts (Sign)
`property_name`	`string`	Ja	Name der Unterkunft (oder Device-ID als Fallback)
`property_city`	`string \| null`	Nein	Stadt der Unterkunft, sofern hinterlegt
`timestamp`	`string`	Ja	ISO 8601 Zeitstempel des Checkout-Events
`source`	`string`	Ja	Immer `"checkyout"`

Beispiel-Payload

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

Signaturverifizierung

Die Signatur ist der HMAC-SHA256-Hash des JSON-Body mit Ihrem Webhook-Secret, als Hex-String. Code-Beispiele finden Sie unter Authentifizierung → Signatur verifizieren.

Retry-Verhalten

Bei fehlgeschlagener Zustellung (Non-2xx-Response, Timeout oder Netzwerkfehler) wiederholt CheckYout den Webhook automatisch mit exponentiellem Backoff:

Versuch	Verzögerung
1. Versuch	Sofort
2. Versuch	Nach 1 Minute
3. Versuch	Nach 5 Minuten

Bei Client-Fehlern (4xx ausser 429) wird nicht wiederholt — diese deuten auf ein Problem in Ihrer Konfiguration hin.

Timeout

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Statuscode. Wir empfehlen, das Event asynchron zu verarbeiten und sofort mit 200 OK zu antworten.

Idempotenz

Jedes Event enthält eine eindeutige event_id (UUID). Verwenden Sie diese zur Deduplizierung, falls ein Event durch Retry mehrfach zugestellt wird.

Empfehlungen

Antworten Sie immer mit 200 OK und verarbeiten Sie das Event asynchron.
Verifizieren Sie die Signatur vor der Verarbeitung.
Speichern Sie das Event persistent, bevor Sie mit 200 antworten, um Datenverlust zu vermeiden.
Implementieren Sie clientseitige Idempotenz basierend auf device_id + timestamp.

Nächster Schritt: Notify API Referenz