Webhook přišel dvakrát: jak zabránit dvojí faktuře nebo expedici

Platební služba oznámí úhradu, ale nedostane včas odpověď. Událost proto pošle znovu. Pokud firemní systém každou zprávu chápe jako nový pokyn, může vystavit druhou fakturu nebo dvakrát uvolnit zásilku. Opakované doručení je běžný integrační scénář, ne exotická chyba.

Stejný požadavek má mít stejný obchodní účinek

Tomuto principu se říká idempotence. Nestačí porovnat text poslední přijaté zprávy. Potřebujete stabilní identifikátor události nebo operace a evidenci výsledku jejího zpracování. Jedna platba se může promítnout do více oznámení, která mají odlišný technický identifikátor, ale nesmějí podruhé spustit stejný obchodní krok.

Kontrola a zápis musí odolat souběhu. Dva procesy, které oba nejprve ověří „ještě neexistuje“, mohou bez další ochrany pokračovat současně. Pomáhá databázová jedinečnost a transakční návrh odpovídající konkrétní operaci.

Potvrzení přijetí není potvrzení všeho

Zprávu lze nejprve bezpečně uložit a teprve potom zpracovat. Odesílateli vracejte odpověď podle smluveného protokolu, nikoli úspěch před skutečným uložením. Selhání navazující fakturace musí zůstat viditelné a opravitelné, i když transport zprávy proběhl správně.

Ověřte původ a integritu oznámení podle dokumentace poskytovatele.
Nevěřte pouze částce a stavu z neověřeného vstupu.
Uchovejte vazbu mezi událostí, objednávkou a výslednou operací.
Zajistěte řízené opakování bez znovuvytvoření hotových kroků.

Události mohou přijít v jiném pořadí

Oznámení o stornu může předběhnout starší informaci o zpracování. Systém proto nemá bezpodmínečně přepisovat stav poslední doručenou zprávou. Použijte dovolené přechody a podle potřeby ověřte aktuální stav u zdroje.

Čtyři povinné testy integrace

Pošlete stejnou zprávu dvakrát, dvakrát současně, v obráceném pořadí s další událostí a s výpadkem uprostřed navazujícího kroku. Ověřte počet faktur, skladových pohybů a zpráv zákazníkovi. Funkční API volání samo o sobě neprokazuje spolehlivou integraci; rozhodující je správný obchodní výsledek i po opakování.

Objevují se ve vašich systémech duplicity?

Projdeme tok událostí a navrhneme bezpečné opakování platebních i provozních integrací.

Konzultovat integrační problém