słownik automatyzacji

Idempotentność

Idempotentność to właściwość operacji, przy której wielokrotne wywołanie z tymi samymi parametrami daje ten sam wynik co pierwsze wywołanie, bez dodatkowych efektów ubocznych. W automatyzacji procesów idempotentność webhooków i operacji na danych jest fundamentem niezawodności systemu przy awariach i ponowieniach.

Wyobraź sobie webhook od Stripe informujący o płatności. Stripe gwarantuje dostarczenie, ale nie gwarantuje dostarczenia dokładnie raz. Sieciowy timeout, restart serwera, chwilowa niedostępność endpointu powodują, że to samo zdarzenie płatności może dotrzeć dwa, trzy razy. Jeśli Twój handler nie jest idempotentny, klient dostanie dwie faktury za jedną płatność.

Implementacja idempotentności: każde zdarzenie ma unikalny identyfikator (u Stripe to ID eventu, np. evt_1ABC...). Przy pierwszym przetworzeniu zapisujesz ten ID do tabeli idempotency_keys. Przy każdym kolejnym wywołaniu sprawdzasz: jeśli ID już istnieje w tabeli, zwracasz 200 (bo obsłużyłeś) i kończysz bez wykonywania logiki biznesowej. Ta prosta kontrola eliminuje podwójne faktury, podwójne emaile i wszelkie inne duplikaty.

Idempotentność to nie tylko kwestia webhooków. Każda operacja zapisu, którą można ponowić (retry przy błędzie sieci, ponowne uruchomienie workflow), powinna być idempotentna. SQL INSERT ... ON CONFLICT DO NOTHING zamiast zwykłego INSERT to klasyczny wzorzec.

W praktyce

W każdym webhook handlerze n8n, który buduję, pierwsze dwa węzły to zawsze: weryfikacja podpisu + sprawdzenie idempotency key. Klucz to SHA256 z kombinacji providera, event ID i event type. Przed jakąkolwiek logiką biznesową sprawdzam tabelę idempotency_keys w Postgres. Przy konflikcie workflow kończy się sukcesem bez dalszego przetwarzania. Dodatkowa ochrona: timestamp zdarzenia musi być świeższy niż 5 minut (anti-replay dla webhooków ze starymi zdarzeniami). Te dwa kroki razem eliminują zarówno duplikaty jak i ataki replay.

Powiązane

← Wróć do słownika