Webhooks en herstel van gebeurtenissen

Stap 1 — Configureer een bestemming

Een beheerder opent een API-sleutel in API & integraties en voegt een HTTP- of HTTPS-bestemming toe. HTTPS wordt aanbevolen; de interface waarschuwt voor HTTP, directe IP-adressen en lokale adressen zonder registratie te blokkeren. De middleware moet de URL kunnen bereiken. Iedere bestemming hoort bij de sleutel en heeft een eigen ondertekeningsgeheim, dat alleen bij creatie of rotatie verschijnt. Selecteer zo nodig een deel van de gebeurtenistypen. Rotatie of intrekking van de sleutel raakt ook haar bestemmingen; zorg dat de ontvanger gereed is vóór activering.

“Ontvanger gereed” betekent dat URL en geheim zijn ingesteld, niet dat al een gebeurtenis is aangekomen. Houd uitgaande API-opdrachten, inkomende webhookleveringen en herstel via GET /v1/events als drie afzonderlijke stromen bij. Een PUT of POST van je backend is geen ontvangen webhook.

Vergelijk voor koppeling de exacte URL bij de API-sleutel met de ontvanger en bewaar het teruggegeven geheim. De API toont dit later niet opnieuw. Meld pas een live levering nadat een ondertekende inkomende POST is geverifieerd; alleen een lokaal geheim bewijst geen levering.

Stap 2 — Verifieer vóór verwerking

Elke levering bevat webhook-id, webhook-timestamp en webhook-signature. Standard Webhooks gebruikt HMAC-SHA256 over de UTF-8-bytes van webhook-id + "." + webhook-timestamp + ".", gevolgd door de exacte ruwe bodybytes. Het geheim begint met whsec_ en bevat een Base64-gecodeerde sleutel. Vergelijk de Base64-handtekening van een v1,-waarde in constante tijd.

Weiger timestamps die meer dan vijf minuten van de servertijd afwijken. Verifieer vóór JSON-parsing. Controleer dat body-id gelijk is aan webhook-id en bewaar dit ID vóór bedrijfsgevolgen. Antwoord snel met 2xx.

Levering is at least once en de volgorde is niet gegarandeerd. Dedupliceer op gebeurtenis-ID. Een voltooiingsgebeurtenis bevat ID’s en API-paden; haal volledige gegevens op via de geauthenticeerde API. De hoofdgebeurtenissen zijn rental.departure.completed en rental.return.completed; correcties en PDF-gereedheid hebben aparte typen. Zie de Rental OpenAPI-definitie.

Stap 3 — Reconcilieer na elk signaal

Lees na een geldige voltooiingswebhook het Rental-dossier of de rapportindex opnieuw. JSON kan vóór PDF gereed zijn; volg de 200/202-stroom in Rapporten en bewijs. Blokkeer het proces niet onbeperkt op een webhook: periodieke reconciliatie blijft geldig.

Stap 4 — Herstel gemiste gebeurtenissen

Gebruik na uitval GET /v1/events met cursor en eventueel created_after. Gebeurtenissen blijven 30 dagen beschikbaar. Verplaats je opgeslagen cursor pas nadat de pagina is verwerkt. De platformlevering probeert maximaal acht keer over 48 uur; een beheerder kan recente fouten in API & integraties bekijken en opnieuw proberen.

Beschouw gebeurtenissen als meldingen en geauthenticeerde resourceroutes als bron voor actuele gegevens. Rapportidentiteiten en versies beschrijft veilige archivering.

Als geen ondertekende gebeurtenis aankomt

Controleer dat bestemming, API-sleutel en omgeving overeenkomen met je API-aanvragen.
Controleer de selectie van rental.departure.completed en rental.return.completed en de exacte URL.
Bekijk de aflevergeschiedenis. Niet-2xx, timeout of geweigerde handtekening wijst op de ontvanger; corrigeer een uitgeschakelde of ingetrokken sleutel vóór herhaling.
Voer direct GET /v1/events uit zodat verwerking doorgaat tijdens herstel.
Roteer het geheim alleen wanneer de ontvanger het passende geheim kwijt is en werk hem bij vóór een nieuwe levering.

Geef bij escalatie gebeurtenis- of leverings-ID en API-request_id, nooit het geheim.