Webhooks und Ereigniswiederherstellung

Schritt 1 — Ziel konfigurieren

Ein Administrator öffnet unter API & Integrationen einen API-Schlüssel und fügt ein HTTP- oder HTTPS-Ziel hinzu. HTTPS wird empfohlen. Bei HTTP, direkten IP-Adressen und lokalen Adressen warnt die Oberfläche, verhindert die Registrierung aber nicht. Das Middleware muss die URL erreichen können, damit Zustellungen funktionieren. Ein Ziel gehört zu diesem Schlüssel und besitzt ein eigenes Signaturgeheimnis, das nur beim Erstellen oder Rotieren angezeigt wird. Wählen Sie Ereignistypen aus, wenn der Empfänger nur einen Teil des Feeds benötigt. Das Rotieren oder Widerrufen eines Schlüssels wirkt sich auch auf dessen Ziele aus; halten Sie einen Empfänger bereit, bevor Sie die Zustellung aktivieren.

„Empfänger bereit“ bedeutet, dass Ziel und Signaturgeheimnis konfiguriert sind — nicht, dass bereits ein Ereignis eingetroffen ist. Führen Sie ausgehende API-Befehle, eingehende Webhook-Zustellungen und die Wiederherstellung über GET /v1/events als drei getrennte Datenströme in Protokollen und Überwachung. Ein von Ihrem Backend gesendetes PUT oder POST ist kein empfangener Webhook.

Vergleichen Sie zur Bestätigung der Kopplung die beim API-Schlüssel angezeigte Ziel-URL exakt mit der vom Empfänger veröffentlichten URL und speichern Sie das für dieses Ziel zurückgegebene Geheimnis. Die API zeigt es später nicht erneut an. Ein Empfänger darf eine Live-Zustellung erst dann als empfangen melden, wenn ein eingehendes signiertes POST erfolgreich geprüft wurde. Ein lokal gespeichertes Geheimnis belegt nur die Konfigurationsbereitschaft, nicht die Zustellung.

Schritt 2 — Vor der Verarbeitung prüfen

Jede Zustellung enthält webhook-id, webhook-timestamp und webhook-signature. Die Signatur folgt Standard Webhooks: HMAC-SHA256 über die UTF-8-Bytes von webhook-id + "." + webhook-timestamp + ".", gefolgt von den exakten unveränderten Bytes des Anfragetexts. Das Geheimnis beginnt mit whsec_; der folgende Signaturschlüssel ist Base64-codiert. Vergleichen Sie die Base64-Signatur eines v1,-Eintrags in konstanter Zeit.

Lehnen Sie Zeitstempel ab, die mehr als fünf Minuten von Ihrer Serverzeit abweichen. Prüfen Sie die Signatur, bevor Sie JSON parsen. Vergewissern Sie sich anschließend, dass die id im Ereignis mit webhook-id übereinstimmt, und speichern Sie diese Kennung, bevor Sie geschäftliche Auswirkungen anwenden. Eine schnelle erfolgreiche 2xx-Antwort bestätigt die Zustellung.

Zustellungen erfolgen mindestens einmal und können in anderer Reihenfolge eintreffen. Deduplizieren Sie nach Ereigniskennung. Ein Abschlussereignis enthält Kennungen und API-Pfade; lesen Sie den aktuellen Bericht oder Rental-Vorgang über die authentifizierte API, wenn Sie vollständige Daten benötigen. Die Abschlussereignisse sind rental.departure.completed und rental.return.completed. Korrekturen und PDF-Bereitschaft haben eigene Ereignisse. Alle Ereignistypen und Felder stehen in der Rental-OpenAPI-Webhook-Definition.

Schritt 3 — Nach jedem Signal abgleichen

Lesen Sie nach einem gültigen Abschluss-Webhook den aktuellen Rental-Vorgang oder Berichtsindex über die authentifizierte API. JSON-Berichte können vor dem PDF bereitstehen; folgen Sie dem unter Berichte und Nachweise beschriebenen Ablauf für 200 und 202. Blockieren Sie den Geschäftsablauf nicht unbegrenzt in Erwartung eines Webhooks. Ein regelmäßiger Abgleich bleibt auch bei gesundem Empfänger gültig.

Schritt 4 — Verpasste Ereignisse nachholen

Verwenden Sie GET /v1/events mit Cursor und optionalem Filter created_after, um nach einem Ausfall abzugleichen. Ereignisse bleiben 30 Tage verfügbar. Setzen Sie den gespeicherten Cursor erst weiter, nachdem Sie die empfangene Seite verarbeitet haben. War der Empfänger nicht erreichbar, wiederholt die Plattform fehlgeschlagene Zustellungen bis zu achtmal innerhalb von 48 Stunden. Ein Administrator kann aktuelle Fehler unter API & Integrationen einsehen und erneut zustellen.

Behandeln Sie den Ereignisfeed als Benachrichtigung und die authentifizierten Ressourcenrouten als Quelle der aktuellen Daten. Berichtskennungen und Versionen erklären die sichere Archivierung.

Wenn kein signiertes Ereignis erscheint

1. Prüfen Sie, ob das Ziel zu demselben API-Schlüssel und derselben Umgebung gehört wie Ihre API-Aufrufe.
2. Prüfen Sie, ob rental.departure.completed und rental.return.completed ausgewählt sind und die exakte Ziel-URL noch aktuell ist.
3. Untersuchen Sie den Zustellverlauf. Eine Nicht-2xx-Antwort, ein Timeout oder eine abgelehnte Signatur ist ein Empfängerfehler; ein deaktivierter oder widerrufener Schlüssel muss vor dem nächsten Versuch korrigiert werden.
4. Rufen Sie sofort GET /v1/events auf, damit die Verarbeitung während der Reparatur weiterläuft.
5. Rotieren Sie das Zielgeheimnis nur, wenn der Empfänger den passenden Wert nicht mehr besitzt. Aktualisieren Sie den Empfänger, bevor Sie die Zustellung erneut versuchen.

Geben Sie dem Support bei einer Eskalation die Ereignis- oder Zustellkennung sowie die request_id der API-Antwort. Senden Sie niemals das Signaturgeheimnis.