Een webhook komt twee keer. Je klantmail hoeft maar één keer.

Je workflow ontvangt een bestelling, maakt een dossier aan en verstuurt een bevestiging. Daarna valt de verbinding weg. De uitvoering kleurt rood. Nog een keer proberen lijkt logisch, maar misschien is die mail allang verzonden. Betrouwbare automatisering vraagt daarom om een antwoord op twee vragen: heb ik deze gebeurtenis al gezien, en welke actie is werkelijk uitgevoerd?

Dit artikel beschrijft een ontwerp met fictieve gegevens, geen kant-en-klare productieworkflow. Controleer bij iedere gekoppelde dienst welke teruglees- en herhaalmogelijkheden echt bestaan. Een retry-knop, een groene node of een opgeschoonde invoerlijst bewijst niet dat een externe handeling veilig opnieuw kan.

Geef de gebeurtenis en de actie een eigen identiteit

Een gebeurtenis-ID helpt twee leveringen van dezelfde webhook te herkennen. Een actie-ID zegt welk effect je bedoelt. Voor een fictieve order kan dat order TEST-204 plus actie orderbevestiging plus versie 1 zijn. Een later geautoriseerde wijzigingsmail krijgt een andere actieversie. Gebruik geen nieuw willekeurig actie-ID voor iedere retry: dan lijken herhalingen opnieuw unieke acties.

Het hangt van de bron af welke sleutel betrouwbaar is. Twee verschillende webhook-events kunnen over dezelfde bestelling gaan. Alleen het event-ID vergelijken voorkomt dan niet twee bevestigingen. Andersom kan alleen het ordernummer vergelijken een legitieme latere wijziging blokkeren. Leg daarom vooraf vast wanneer je hetzelfde effect bedoelt en wanneer de klant echt iets nieuws moet ontvangen.

Ontdubbelen is één controle, geen volledige transactielaag

De Remove Duplicates-node van n8n kan gelijke items binnen de huidige invoer of eerder geziene waarden uit voorgaande uitvoeringen filteren. Kies de juiste modus en velden. De historie heeft een ingestelde omvang en kan worden gewist. Gebruik die historie daarom niet ongemerkt als permanent bewijs dat een betaling, order of mail is afgehandeld.

Een aparte actieregistratie kan de toestanden klaar voor verwerking, bezig, bevestigd en onzeker bijhouden. Het reserveren van een actie moet bestand zijn tegen twee gelijktijdige uitvoeringen. Een gewone lookup gevolgd door een losse insert laat ruimte voor een race: beide uitvoeringen kunnen dezelfde lege uitkomst lezen. Laat een technisch beheerder een passende unieke sleutel en atomaire reservering in de gekozen opslag ontwerpen. Ook een record dat na een crash op bezig blijft staan vraagt eerst onderzoek en teruglezing; alleen ouderdom is geen bewijs dat veilig opnieuw kan worden uitgevoerd.

Werk de onzekere uitkomst expliciet uit

START
Webhook EVT-204 hoort bij order TEST-204. Actiesleutel: TEST-204:bevestiging:v1.

EERSTE POGING
De maildienst accepteert de opdracht, maar het antwoord bereikt n8n niet. n8n ziet een timeout.

VEILIGE STATUS
De actie krijgt “onzeker”, niet automatisch “mislukt”. Een tweede webhook mag de mail niet meteen opnieuw laten versturen.

VERVOLG
Lees bij de maildienst terug op de opgeslagen referentie, als die dat ondersteunt. Bij aantoonbaar verzonden: sla het externe bericht-ID op en markeer bevestigd. Zonder betrouwbaar bewijs: leg de beslissing aan een beheerder voor.

Een externe API kan herhaalde requests met dezelfde idempotentiesleutel ondersteunen. Stripe documenteert zo’n mechanisme, met regels die per API-versie verschillen. Dat is een concreet voorbeeld van ondersteuning bij de ontvangende dienst, geen bewijs dat jouw maildienst of CRM hetzelfde doet. Controleer scope, bewaartermijn, gedrag bij gewijzigde gegevens en gelijktijdige requests in de documentatie van jouw doel-API.

Maak herstel onderdeel van het ontwerp

1. Valideer gebeurtenis, verplichte velden en de afzender van de webhook voordat je een externe actie voorbereidt.
2. Bepaal de stabiele actiesleutel en vergelijk de inhoud met een eventueel bestaand actierecord. Een gelijke sleutel met andere inhoud vraagt onderzoek.
3. Reserveer de actie op een manier die gelijktijdige verwerking uitsluit. Bewaar alleen noodzakelijke gegevens en referenties.
4. Voer de toegestane actie uit en registreer het bevestigde externe ID. Laat afhankelijke acties pas starten wanneer hun voorganger aantoonbaar klaar is.
5. Behandel verbindingsverlies na een schrijfactie als een mogelijk onzekere uitkomst. Lees terug voordat je opnieuw schrijft.
6. Stuur een foutmelding met de relevante execution- en actiereferentie naar de verantwoordelijke. Verwerk geen geheimen of volledige klantinhoud in het alarm.

n8n ondersteunt aparte error workflows via een Error Trigger; foutgegevens kunnen onder meer een verwijzing naar de uitvoering en een retryOf-veld bevatten. Gebruik die informatie voor diagnose. Een foutmelding mag niet stilzwijgend het startschot zijn voor herhaling van alle eerder geslaagde stappen.

Test de grenzen zonder echte verzending

Gebruik eerst een testomgeving of vervang de externe actie door een lokale teller. Bied dezelfde gebeurtenis twee keer aan, voer twee kopieën tegelijk uit, onderbreek na het nagebootste effect maar vóór de bevestiging en probeer een nieuw event voor dezelfde actie. Verwacht telkens één effect of een expliciete blokkade bij onzekerheid. Controleer daarnaast dat een echte nieuwe actieversie niet onterecht wordt weggefilterd.

Leg per proef de invoer, verwachte status en waargenomen uitkomst vast. Pas na die controle koppel je echte acties met de juiste toestemming. Deze aanpak maakt herstel bespreekbaar en toetsbaar. Hij belooft geen algemene exactly-once-garantie over meerdere systemen; die hangt af van de technische mogelijkheden en grenzen van iedere schakel.