Wat is idempotentie, en hoe ga je om met dubbele webhooks?

Een verbroken verbinding kan je onzeker laten of een verzendverzoek is geslaagd. Een verloren bevestiging kan er ook voor zorgen dat een webhookafzender een event aflevert dat je applicatie al heeft opgeslagen.

Deze fouten gebeuren in tegengestelde richtingen. Bird kan een herhaald API-verzoek herkennen aan de hand van een sleutel die je meegeeft. Je webhookontvanger heeft een eigen registratie nodig van events die al geaccepteerd zijn.

Hoe probeer ik een verzending veilig opnieuw?

Gebruik bij elke nieuwe poging dezelfde Idempotency-Key en een identiek verzoek. De garantie is dat het verzoek precies één keer wordt geaccepteerd: overeenkomende nieuwe pogingen binnen drie uur moeten leiden tot één geaccepteerde bewerking, ook als je het antwoord kwijt bent.

Je kiest de sleutel zelf, maximaal 255 tekens, en behoudt deze bij retries. Een stabiele waarde zoals welcome-user/usr_abc123 kan één welkomstberichtbewerking identificeren nadat je proces opnieuw is gestart.

De header is van toepassing op muterende verzoeken zoals POST, PATCH en DELETE. Een verzoek zonder sleutel wordt verwerkt zonder deze deduplicatie. GET negeert de header omdat het lezen van de resource al veilig herhaalbaar is.

Bird retourneert het opgeslagen antwoord voor een overeenkomend voltooid verzoek, inclusief de oorspronkelijke status en body. Het antwoord bevat Idempotency-Replay: true, zodat je dat hergebruik in je logs kunt herkennen.

De idempotentiegids beschrijft een standaard van drie uur voor het venster van het voltooide antwoord. Als je na afloop daarvan opnieuw probeert, kan het verzoek als nieuwe bewerking worden uitgevoerd. Vertrouw niet permanent op die sleutel om dubbele verzendingen te voorkomen.

Bird-SDK's genereren een sleutel voor een mutatie en hergebruiken die bij hun interne retries. De Bird CLI genereert ook een sleutel voor een muterend verzoek wanneer er geen aanwezig is. Stel --idempotency-key expliciet in wanneer afzonderlijke commando-aanroepen dezelfde bewerking moeten delen.

Gebruik voor SMTP-indiening de X-Bird-Idempotency-Key-berichtheader. Hiermee kan een opnieuw ingediende indiening dezelfde bewerking identificeren.

Wat gebeurt er als ik een sleutel verkeerd hergebruik?

Bird weigert conflicterend sleutelgebruik in plaats van een antwoord voor een andere bewerking te retourneren.

De vergelijking omvat de methode, het endpoint, padparameters, querystring en body. Bij JSON verandert het wijzigen van witruimte de verzoekidentiteit, dus bewaar de oorspronkelijke body bij retries.

Als het oorspronkelijke verzoek nog bezig is, wacht dan voordat je opnieuw probeert. Gebruik dezelfde sleutel en hetzelfde verzoek, zodat de nieuwe poging de oorspronkelijke bewerking identificeert.

De API bewaart een 5xx-antwoord niet als voltooid antwoord. Probeer een time-out of serverfout opnieuw met begrensde backoff, dezelfde sleutel en een identiek verzoek binnen drie uur. De garantie dat het verzoek precies één keer wordt geaccepteerd, dekt ook een verloren antwoord.

Een 4xx-afwijzing kan worden bewaard. Gebruik een nieuwe sleutel voor een gecorrigeerd verzoek: een ongewijzigde nieuwe poging speelt een bewaarde afwijzing opnieuw af, en gewijzigde invoer conflicteert met die bewaarde sleutel.

Waarom ontvang ik dezelfde webhook twee keer?

Bird kan een event opnieuw proberen dat je ontvanger al heeft opgeslagen, als het geen succesvol antwoord ontvangt.

Een ontvanger kan een event opslaan vlak voordat de verbinding wegvalt. Bird ziet geen succesvolle bevestiging en probeert opnieuw, ook al heeft de ontvanger het event al.

Elke nieuwe poging behoudt dezelfde webhook-id-header, die het event identificeert. Een replay van een mislukte aflevering behoudt die identifier ook, zodat beide als hetzelfde event herkend kunnen worden.

Hoe maak ik mijn handler idempotent?

Sla elke webhook-id op onder een unieke databaseconstraint voordat je het werk van het event inplant.

Controleren of een rij al bestaat voordat je invoegt laat een race condition open: twee gelijktijdige verzoeken kunnen allebei geen rij zien. Laat de database dubbele identifiers afwijzen.

Sla de identifier en de taak op in dezelfde transactie. Dit voorkomt dat een identifier wordt geregistreerd zonder dat er werk in de wachtrij staat.

1. Verifieer het verzoek en voeg vervolgens de identifier en taak in binnen dezelfde transactie.
2. Retourneer 2xx nadat die transactie is gecommit, zodat Bird kan stoppen met opnieuw proberen.
3. Verwerk de opgeslagen taak in een worker die zijn eigen acties veilig kan herhalen.

Retourneer bij een dubbele identifier die al gecommit is een succes zonder een nieuwe taak aan te maken. Retourneer bij een mislukte transactie een fout zodat Bird opnieuw probeert.

Houd traag werk buiten de ontvanger, want wachten erop kan ervoor zorgen dat het verzoek een time-out krijgt. Een worker kan opnieuw proberen om redenen die los staan van webhookaflevering, dus alleen de ontvanger beschermen is onvoldoende.

Events kunnen ook in de verkeerde volgorde aankomen. Vergelijk eventtijden in timestamp voordat je nieuwere status overschrijft. Mislukte webhook-retries bevat het voorbeeld met gedeeltelijke kosten.

Waar moet je niet op vertrouwen?

Ga er niet van uit dat deduplicatie van verzoeken dubbele neveneffecten onmogelijk maakt.

Bij een ondersteunde HTTP-schrijfbewerking koppelt Bird de idempotentiesleutel aan de werkruimte of organisatie van het verzoek. Ondersteunde staff-bewerkingen gebruiken in plaats daarvan het handelende staff-account. Als bescherming niet beschikbaar is, retourneert Bird 503 E01033 IdempotencyUnavailable voordat die poging wordt uitgevoerd. Dit bepaalt niet de uitkomst van een eerdere poging. De garantie van precies-één-keer-acceptatie dekt overeenkomende nieuwe pogingen binnen drie uur. Controleer de berichtstatus om de aflevering te bevestigen. Als de nieuwe pogingen op zijn of het venster is verlopen, controleer dan de uitkomst van de oorspronkelijke bewerking voordat je opnieuw indient.

Op dezelfde manier onderscheidt webhook-id herhaalde afleveringen van één event. Afzonderlijke events hebben afzonderlijke identifiers. Je applicatie beslist nog steeds of die events het herhalen van dezelfde actie rechtvaardigen.

Idempotentie beschrijft hoe API verzoeken opnieuw proberen afhandelt. Webhooks behandelt de afzonderlijke afleveringsgaranties die je ontvanger afhandelt.