---
title: "Idempotentní n8n webhook: jak zabránit duplicitám"
description: "Jak navrhnout n8n webhook, který při dvojkliku, timeoutu ani opožděném retry nevytvoří druhou rezervaci, fakturu nebo kontakt v CRM."
url: "https://blog.lucidmark.cz/blog/idempotentni-n8n-webhook-jak-zabranit-duplicitam"
language: "cs"
author: "Roman Mrózek"
author_url: "https://blog.lucidmark.cz/autor/romanmrozek"
publisher: "LucidMark s.r.o."
date_published: "2026-08-05T07:03:43.617Z"
date_modified: "2026-08-05T07:03:43.575Z"
category: "Vývoj"
reading_time_minutes: 4
sources:
  - title: "n8n Docs: Webhook node"
    url: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/"
  - title: "n8n Docs: Error handling"
    url: "https://docs.n8n.io/flow-logic/error-handling/"
  - title: "PostgreSQL Docs: INSERT a ON CONFLICT"
    url: "https://www.postgresql.org/docs/current/sql-insert.html"
---

# 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.

Autor: Roman Mrózek | Publikováno: 5. 8. 2026 | Kategorie: [Vývoj](https://blog.lucidmark.cz/kategorie/vyvoj)  
Původní článek: https://blog.lucidmark.cz/blog/idempotentni-n8n-webhook-jak-zabranit-duplicitam

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](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/).

## 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](https://www.postgresql.org/docs/current/sql-insert.html) 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](https://blog.lucidmark.cz/blog/administrace-kurzu-bez-excelu-case-study-vodnicek) je právě společný stav dat důležitější než další izolovaná tabulka. [LucidMark](https://lucidmark.cz) 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](https://docs.n8n.io/flow-logic/error-handling/).

## 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 host@example.cz, 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.

## Zdroje a další čtení

1. [n8n Docs: Webhook node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/)
2. [n8n Docs: Error handling](https://docs.n8n.io/flow-logic/error-handling/)
3. [PostgreSQL Docs: INSERT a ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html)
