Přeskočit na obsah
Zpět na blog
Vývoj

Idempotentní n8n webhook: jak zabránit duplicitám

Jak navrhnout n8n webhook, který při dvojkliku, timeoutu ani opožděném retry nevytvoří druhou rezervaci, fakturu nebo kontakt v CRM.

Roman Mrózek
4 min čtení
Abstraktní modré světelné datové linky připomínající tok událostí
Praktický návrh idempotentního n8n webhooku pro potvrzení rezervace bez duplicitních objednávek, faktur a kontaktůFoto: Luke Jones / Unsplash

Idempotentní n8n webhook zpracuje stejné potvrzení rezervace opakovaně, ale objednávku, fakturu nebo kontakt založí jen jednou. Nejde o vypnutí retry. Jde o návrh, který očekává dvojklik, ztracenou odpověď i opožděné doručení a pro každou situaci vrátí předvídatelný výsledek.

Modelový případ je jednoduchý: rezervační formulář odešle událost reservation.confirmed. Workflow má uložit rezervaci, najít nebo vytvořit kontakt v CRM a zadat vystavení faktury. Když odesílatel po timeoutu událost zopakuje, druhý běh nesmí znovu provést žádný z těchto zápisů.

Proč běžný webhook vytváří duplicity?

Protože doručení webhooku obvykle znamená alespoň jednou, nikoli právě jednou. Odesílatel nemusí poznat, že server operaci dokončil, pokud se cestou ztratí odpověď. Stejný požadavek proto pošle znovu.

Typická chyba v n8n vypadá takto: Webhook spustí vytvoření rezervace, CRM kontaktu a faktury, až potom odešle odpověď. Databázový zápis proběhne, ale odpověď se zpozdí. Odesílatel vyhodnotí timeout jako neúspěch a provede retry. Nová execution neví, že první běh už změnil data.

První obrana proto není IF uzel hledající podobný e-mail. Shoda podle e-mailu může spojit dvě legitimní rezervace stejného hosta. Potřebujete identitu události, atomický zápis a evidenci jejího životního cyklu. Konfiguraci vstupu a způsob odpovědi popisuje oficiální dokumentace Webhook node.

Jak vytvořit a uložit idempotency key?

Klíč musí jednoznačně označit obchodní událost a zůstat stejný při každém retry. Nejlepší je, když ho vytvoří zdrojový systém ještě před prvním odesláním, například reservation-confirmed:rsv_8f31. Náhodné ID generované až uvnitř n8n je pro deduplikaci nepoužitelné, každý běh by dostal jiné.

Když zdroj vlastní klíč neposílá, sestavte stabilní otisk z neměnných polí, například typu události, ID rezervace a verze události. Do klíče nedávejte čas přijetí ani pořadí execution. Hash není bezpečnostní kontrola, pouze kompaktní identifikátor. Autenticitu požadavku řešte odděleně podpisem webhooku nebo autentizací.

Úložiště processed_events může obsahovat idempotency_key s unikátním omezením, status, payload_hash, started_at, completed_at, response_body a error_code. První databázový krok se pokusí klíč vložit se stavem processing. Použijte atomické INSERT s konfliktní větví, ne kombinaci SELECT a následného INSERT. Mezi dvěma kroky by mohly projít dva souběžné běhy. Chování PostgreSQL ON CONFLICT je pro tento zámek vhodný základ.

Jak má vypadat workflow potvrzení rezervace?

Workflow rozdělte na bránu, obchodní operaci a dokončení. Brána ověří vstup, přečte idempotency key a atomicky založí nebo načte záznam události. Teprve vlastník nově založeného záznamu smí pokračovat k zápisům.

  1. Webhook přijme potvrzení a zkontroluje povinná pole, autentizaci a typ události.
  2. Databáze provede claim klíče. Nový záznam získá stav processing a identifikátor běhu.
  3. Existující completed vrátí uloženou úspěšnou odpověď bez dalších zápisů.
  4. Existující processing vrátí přijetí ke zpracování, případně workflow krátce vyčká a stav znovu načte.
  5. Vlastník claimu provede upsert kontaktu, založení rezervace a zadání faktury s vlastními unikátními obchodními klíči.
  6. Po dokončení uloží status completed a stejnou response_body, kterou dostane první i každý další pokus.

Důležitá je druhá ochranná vrstva. CRM kontakt může používat unikátní externí ID, rezervace reservation_id a faktura reference reservation_id. Kdyby běh selhal mezi vzdáleným zápisem a změnou processed_events, opakování udělá upsert nebo načte existující objekt, nikoli slepé create.

Podobný princip dává smysl u systému kurzů, kde rezervace, platby a kapacity patří do jednoho toku. U projektu Vodníček popsaného v článku Administrace kurzů bez Excelu je právě společný stav dat důležitější než další izolovaná tabulka. LucidMark u custom systémů navrhuje workflow tak, aby vlastnictví dat i kritické přechody zůstaly čitelné.

Jak řešit časové okno, rozpracovaný stav a retry?

Časové okno neurčuje, kdy smíte zapomenout obchodní identitu. Určuje, jak dlouho považujete stav processing za aktivní. Zvolte ho podle nejdelší očekávané operace a timeoutů napojených služeb, hodnotu uložte do konfigurace a sledujte ji v logu.

Čerstvý processing nesmí převzít druhý běh. Starý processing po překročení okna lze označit jako recovery_pending a před převzetím ověřit skutečný stav v cílových systémech. Nejprve vyhledejte rezervaci, kontakt a fakturu podle externích referencí. Teprve chybějící krok opakujte. To je konkrétní význam bezpečného retry: read-first kontrola, unikátní klíče, upsert a audit každého přechodu.

Retry používejte jen pro přechodné chyby, například timeout nebo dočasnou nedostupnost. Chybná data bez povinného reservation_id se opakováním neopraví. Takový běh označte failed_permanent, vraťte srozumitelnou chybu a uchovejte technický detail v logu. Provozní selhání lze směrovat do samostatného error workflow podle dokumentace n8n k error handlingu.

Jak idempotentní n8n webhook otestovat?

Test musí ověřit výsledek v databázi i cílových službách, ne pouze zelenou execution. Použijte pseudodata: event_id evt_res_001, type reservation.confirmed, reservation_id rsv_8f31, customer_external_id cus_104, email [email protected], amount 4200 CZK a occurred_at 2026-08-05T09:30:00Z. Částka a čas jsou pouze testovací vstup, nikoli provozní statistika.

  • Dvojklik: odešlete dva shodné požadavky souběžně. Očekávejte jeden claim, jednu rezervaci, jednu fakturu a shodnou výslednou odpověď.
  • Timeout po zápisu: po vytvoření rezervace uměle přerušte běh před completed. Retry musí rezervaci najít podle reservation_id a pokračovat jen chybějícím krokem.
  • Opožděné opakování: stejnou událost odešlete po skončení okna processing. Completed záznam musí stále vrátit uložený výsledek bez nové faktury.
  • Změněný payload pod stejným klíčem: payload_hash se neshoduje. Workflow má požadavek odmítnout a zalogovat konflikt, ne přepsat původní událost.

Idempotentní n8n webhook tedy nestojí na jednom IF uzlu. Potřebuje stabilní klíč, atomický claim, explicitní stavy processing, completed a failed, uloženou odpověď a idempotentní zápisy v každém cílovém systému. Když k tomu přidáte read-first obnovu a testy skutečných následků, retry se změní z rizika na řízenou součást integrace.

Mohlo by Vás zajímat

Všechny články
Spolupráce

Řešíte něco podobného?

Krátký hovor, žádná prezentace. Řekneme, co bychom postavili, a také kdy to nedává smysl.

Newsletter

Nové články rovnou do e-mailu.

Posíláme jen nové články. Odhlásíte se jedním klikem.

Zpět nahoru