Een webhook is een melding van een ander systeem. Het is verleidelijk om die melding te beschouwen als een strak geordende instructie: ontvang de melding, werk een record bij en geef aan dat de actie is geslaagd. Voor echte integraties is een zorgvuldiger afsprakenpakket nodig.
Dezelfde gebeurtenis kan meer dan eens plaatsvinden. Een latere gebeurtenis kan eerder plaatsvinden. De afzender kan het opnieuw proberen omdat hij nooit een antwoord heeft ontvangen, zelfs als de ontvanger zijn taak al heeft voltooid. Ik houd vanaf het begin rekening met deze omstandigheden bij het ontwerpen.
Houd de ontvangstgrens klein
De ontvanger moet de levering verifiëren, de basisvorm ervan controleren, deze duurzaam vastleggen en deze bevestigen volgens het protocol van de aanbieder. Daarna kunnen er kostbare zakelijke verwerkingsstappen volgen.
Bij de verificatie van handtekeningen moet gebruik worden gemaakt van de door de aanbieder vereiste weergave. Wanneer de handtekening de oorspronkelijke verzoekbytes bedekt, kan het eerst parseren en opnieuw serialiseren van JSON ertoe leiden dat de te verifiëren gegevens veranderen. Mislukte verificaties mogen nooit doorgaan naar de normale verwerking.
Duurzaamheid is net zo belangrijk. Als er een bevestiging van ontvangst wordt teruggestuurd voordat de gebeurtenis is vastgelegd, ontstaat er een tijdsvenster waarin het proces kan vastlopen en werk verloren kan gaan waarvan de afzender denkt dat het is geaccepteerd. Een wachtrij in het geheugen sluit dat tijdsvenster niet af.
Ontdubbele bonnen en zakelijke handelingen
Ik sla de aanbieder, het gekoppelde account en de gebeurtenis-ID op onder een uniekheidsvoorwaarde in de database. Hierdoor worden gelijktijdige dubbele leveringen samengevoegd tot één opgeslagen ontvangstbewijs.
Een gebeurtenis-ID is echter niet altijd hetzelfde als een bedrijfsactie-ID. Twee verschillende gebeurtenissen kunnen op legitieme wijze dezelfde bron beschrijven of dezelfde vervolgactie teweegbrengen. De bedrijfsactie heeft een eigen identiteit en eigen overgangsregels nodig.
In de webhook-documentatie van Stripe wordt expliciet melding gemaakt van dubbele leveringen en wordt de volgorde van levering niet gegarandeerd. Ik gebruik die gedocumenteerde gedragingen als uitgangspunt voor het ontwerp van de ontvanger, in plaats van ervan uit te gaan dat de timing die tijdens een ontwikkelingssessie wordt waargenomen, een vaststaand gegeven is.
Modelleer toestandsovergangen in plaats van de volgorde van aankomst
Overweeg een integratie via een abonnement. Een vertraagde melding mag een recentere status niet zomaar overschrijven. Soms is de juiste aanpak om de actuele, gezaghebbende bron op te halen en de lokale weergave hiermee in overeenstemming te brengen.
Bij bewerkingen waarbij historische overgangen nodig zijn, behoud ik de gebeurtenis en pas ik domeinspecifieke regels toe. Een tijdstempel alleen is mogelijk onvoldoende om de volgorde vast te stellen, vooral wanneer meerdere wijzigingen hetzelfde tijdstempel hebben of wanneer verschillende systemen verschillende klokken gebruiken.
De keuze hangt af van het doel van de gegevens. Voor een lokale statusindicator is wellicht alleen de huidige status nodig. Een grootboek of auditlogboek heeft daarentegen de feitelijke volgorde en betekenis van de wijzigingen nodig. Eén algemene “last write wins”-verwerking kan niet op veilige wijze aan beide doelen voldoen.
Maak verwerkingsfouten zichtbaar
Ik maak een onderscheid tussen de ontvangststatus en de verwerkingsstatus. Een geaccepteerde gebeurtenis kan nog steeds de status ‘in behandeling’, ‘opnieuw proberen’, ‘voltooid’ of ‘in afwachting van onderzoek’ hebben. Dit onderscheid voorkomt dat een goed HTTP-responspercentage een defecte integratie maskeert.
Voor elke verwerkingspoging moet een beleid met een limiet voor herhalingspogingen gelden. Wanneer het werk niet verder kan, moeten de gebeurtenisreferentie en de reden voor de mislukking worden bewaard in een controle- of dead-letter-wachtrij. Bij het opnieuw uitvoeren moeten dezelfde regels voor ontdubbeling en autorisatie worden toegepast als bij de oorspronkelijke poging.
Nuttige statistieken zijn onder meer de leeftijd van de oudste nog niet verwerkte gebeurtenis, de verwerkingsvertraging, herhaalde storingen en afwijkingen bij de afstemming. Deze geven een duidelijker beeld van de daadwerkelijke vertraging bij de klant dan het totale aantal webhook-verzoeken.
Test wat het netwerk allemaal kan
Mijn testreeks omvat dubbele leveringen, een omgekeerde volgorde van aankomst, een crash na een permanente ontvangst en een time-out na een extern neveneffect. Ik controleer ook of een ongeldige handtekening niet eens een in behandeling zijnde bedrijfsoperatie kan genereren.
Een goed ontworpen webhook-ontvanger geeft het team twee nuttige antwoorden: of de melding veilig is ontvangen en of het beoogde zakelijke effect is gerealiseerd. Door deze antwoorden gescheiden te houden, wordt de integratie veel eenvoudiger in het gebruik.
Bijgewerkt op 25 september 2026.