Idempotentie betekent dat dezelfde technische opdracht meerdere keren veilig kan worden aangeboden zonder het bedrijfsresultaat te verdubbelen. Voor e-commerce is dat essentieel: webhooks worden herhaald, netwerkverbindingen vallen weg en een bevestiging kan ontbreken terwijl de eerste actie al is uitgevoerd. Zonder idempotentie ontstaan dubbele AFAS-orders, herhaalde WooCommerce-notities of zelfs meerdere refunds.
“We verwerken ieder bericht maar één keer” is geen realistische basis. Ontwerp liever een proces waarin herhaling normaal en controleerbaar is.
Waarom berichten dubbel aankomen
Een systeem dat na verzending geen tijdige bevestiging krijgt, weet niet zeker of de ontvanger de opdracht heeft uitgevoerd. Opnieuw proberen is dan verstandig. Ook een webhookleverancier kan hetzelfde event nog eens sturen wanneer het antwoord te laat kwam. Verder kunnen beheerders handmatig een mislukte taak herstarten.
Er zijn dus twee aparte vragen:
- Hebben we dit technische bericht eerder gezien?
- Is het gewenste bedrijfsresultaat al gerealiseerd?
Alleen de eerste vraag beantwoorden is onvoldoende. Een nieuw event kan namelijk opnieuw naar dezelfde order verwijzen, terwijl het resultaat maar eenmaal mag bestaan.
Kies een stabiele identiteit
Gebruik een sleutel die het bedrijfsresultaat beschrijft, zoals de combinatie van webshop, ordernummer en actietype. Voor een refund hoort ook het bedoelde bedrag of de specifieke retouractie bij de identiteit. De sleutel moet bij een herhaalde poging gelijk blijven en mag niet willekeurig opnieuw worden gegenereerd.
Bewaar daarnaast externe referenties. Als een WooCommerce-order al een AFAS-verkoopordernummer heeft ontvangen, kan de koppeling bij herstel controleren of de relatie nog klopt. Een zichtbare titel of klantnaam is geen betrouwbare sleutel: die kan veranderen en is niet per definitie uniek.
Lees vóór je opnieuw schrijft
Stel dat een opdracht naar AFAS of Mollie een time-out geeft. Het is onbekend of de actie is uitgevoerd. Stuur dan niet direct dezelfde mutatie opnieuw. Zoek eerst met de vaste externe identiteit of het bedoelde resultaat al bestaat. Is de uitkomst nog steeds onzeker, leg de actie voor aan een medewerker in plaats van te gokken.
Dit patroon heet ook wel reconciliatie: de integratie vergelijkt de gewenste toestand met de aantoonbare actuele toestand en bepaalt pas daarna de volgende stap. Het kost meer ontwerpwerk dan een eenvoudige retry, maar voorkomt financiële en administratieve schade.
Verschillende acties vragen verschillende bescherming
| Actie | Risico bij herhaling | Passende bescherming |
|---|---|---|
| AFAS-order aanmaken | Dubbele verkooporder | Externe orderreferentie controleren en bewaren |
| WooCommerce-notitie toevoegen | Vervuilde orderhistorie en herhaalde mail | Vaste notitie-identiteit of bestaande uitkomst herkennen |
| Voorraad op waarde zetten | Oude waarde overschrijft nieuwe | Versie/volgorde controleren; schrijven op absolute waarde |
| Refund uitvoeren | Meervoudige geldbeweging | Unieke refundopdracht plus providercontrole |
| Bezorgstatus verwerken | Terugval naar oudere status | Toegestane statusovergangen en eventvolgorde |
Voorkom webhook-echo’s
Dubbele verwerking kan ook door een kringloop ontstaan. Connect past een WooCommerce-order aan, WooCommerce publiceert een nieuw webhookevent en dat event start opnieuw dezelfde actie. Markeer daarom de oorsprong van wijzigingen of herken de reeds verwerkte toestand. Sla alleen op wanneer er daadwerkelijk iets verandert.
Die laatste regel lijkt klein, maar is belangrijk. Een onnodige “save” kan nieuwe hooks, notificaties en vervolgprocessen starten, ook wanneer de inhoud gelijk bleef.
Maak herhalen zichtbaar en gericht
Een beheerder moet niet alleen een rode fout en een algemene knop “opnieuw” zien. Toon welke bedrijfsactie is bedoeld, welke externe stappen al geslaagd zijn en welke stap veilig opnieuw kan worden uitgevoerd. Een meerstapsretour kan bijvoorbeeld al in AFAS zijn vastgelegd terwijl alleen de betaalprovider nog moet worden gecontroleerd.
Gebruik voor automatische retries een limiet en oplopende wachttijd. Permanente invoerfouten worden niet beter door ze eindeloos te herhalen. Zet een taak stil met een begrijpelijke herstelreden wanneer mapping, rechten of brondata moet worden aangepast.
Test juist de onzekere uitkomsten
- Verstuur hetzelfde webhookevent tweemaal.
- Laat het doelsysteem slagen maar verlies de bevestiging.
- Herstart een taak nadat één van meerdere externe stappen al gereed is.
- Verwerk een ouder event nadat een nieuwere status is ontvangen.
- Laat twee workers tegelijk dezelfde order oppakken.
- Controleer of een handmatige retry dezelfde actie-identiteit behoudt.
Idempotentie is daarmee geen losse programmeertechniek, maar een functionele eigenschap van het hele proces. In webshop en ERP betrouwbaar koppelen leggen we uit waarom traceerbaarheid en herstel bij de basis horen. De concrete AFAS-context staat op WooCommerce-AFAS-koppeling, terwijl Yindle Connect de betrokken stromen beheersbaar maakt.
Veelgestelde vragen over veilig herhalen
Is een webhook-ID voldoende?
Nee. Het voorkomt mogelijk dat exact hetzelfde bericht tweemaal wordt verwerkt, maar twee verschillende berichten kunnen dezelfde bedrijfsactie vragen. Gebruik zowel berichtidentiteit als een sleutel voor het bedoelde resultaat, bijvoorbeeld “AFAS-order maken voor winkel X en order Y”.
Zijn statusupdates vanzelf idempotent?
Een absolute status op dezelfde waarde zetten lijkt veilig, maar gekoppelde neveneffecten kunnen alsnog dubbel lopen. Denk aan e-mail, notitie, voorraadmutatie of een vervolgtaak. Controleer daarom niet alleen het veld, maar ook of de bijbehorende bedrijfsactie al aantoonbaar is uitgevoerd.
Hoe lang bewaar je idempotentiesleutels?
Lang genoeg om realistische retries, vertraagde events en handmatig herstel te omvatten. Voor financiële of administratieve resultaten kan de externe referentie onderdeel van de blijvende proceshistorie zijn. Stem bewaartermijnen af op bedrijfsverantwoording en privacy; bewaar niet automatisch volledige payloads wanneer een beperkte identiteit volstaat.
Controleer de bescherming in productie
Monitor hoe vaak duplicaten worden tegengehouden, hoeveel acties na een onzekere uitkomst moeten worden gereconcilieerd en welke handmatige retries plaatsvinden. Een plotselinge stijging kan wijzen op time-outs, veranderde webhookinstellingen of een niet meer stabiele sleutel. Maak het signaal onderzoekbaar zonder gevoelige gegevens breed in logregels op te nemen.
Voor Mollie-acties is ook de officiële documentatie over idempotentiesleutels relevant. Beschouw providerspecifieke bescherming als extra laag; houd daarnaast jouw eigen bedrijfsidentiteit en resultaatcontrole aan.
Wil je controleren of een bestaande koppeling dubbele bedrijfsacties veilig afvangt? Vraag Yindle om een gerichte integratiereview.