InnerWeb
Przejdź do treści

Idempotentny odbiornik webhooków: dobre praktyki

Odbiornik webhooków w systemie bezpieczeństwa musi zakładać, że to samo zdarzenie przyjdzie dwa razy. Ponowienia są cechą mechanizmów dostarczania, nie ich usterką. Idempotentny odbiornik przetwarza powtórkę bez skutków ubocznych: nie dubluje alarmu, wpisu w kanale ani zgłoszenia w systemie zewnętrznym.

300 s
po tym czasie rezerwacja wraca do puli
Źródło: karta
5 s
limit czasu wysyłki zdarzeń recepcji
Źródło: karta
89
wpisów w jednej paczce
Źródło: karta

Dlaczego powtórki są normalne

W trybie outbox wpis w stanie dostarczania, którego rezerwacja trwa dłużej niż 300 sekund, wraca do puli i może zostać odebrany ponownie. Nieudane potwierdzenie cofa wpis do stanu oczekującego i zwiększa licznik prób. Przy takiej konstrukcji odbiornik końcowy od czasu do czasu zobaczy ten sam ładunek drugi raz, a żaden z tych mechanizmów nie jest błędem.

Gwarancja jest więc typu co najmniej raz, nie dokładnie raz. Dla alarmu to wybór słuszny: lepiej dostać alarm dwa razy niż wcale. Cena tego wyboru spada na odbiorcę, który musi być odporny na powtórzenia.

Praktyka 1–3: klucz zdarzenia i znacznik

Pierwsza praktyka: określ klucz identyfikujący zdarzenie. Najlepiej połączenie typu zdarzenia i identyfikatora obiektu z czasem zdarzenia. W zdarzeniach recepcji każdy ładunek niesie czas w formacie ISO 8601 w strefie Europe/Warsaw, co pozwala zbudować taki klucz bez odwołań do systemu źródłowego.

Druga: zapisuj znacznik przetworzenia atomowo, zanim wykonasz skutek uboczny. Wzorzec użyty w samym systemie to znacznik SET NX w Redisie, który blokuje duplikaty alertu o niezaliczeniu szkolenia. Ustawienie znacznika jest operacją atomową: tylko pierwszy odbiorca go zakłada, kolejny widzi, że wpis jest zajęty.

Trzecia: zwalniaj znacznik, gdy wykonanie się nie powiodło. System robi dokładnie tak: nieudana wysyłka zwalnia blokadę, aby alert mógł wyjść ponownie. Odbiornik, który znaczy zdarzenie jako obsłużone przed wykonaniem akcji i nie cofa znacznika po błędzie, zamienia przejściową awarię w trwałą utratę alarmu.

Parametry, od których zależą powtórki

Parametry, od których zależą powtórkiWykres słupkowy: 300 sekund zwrotu rezerwacji, 89 wpisów w paczce, limit wysyłki 5 sekund.0100200300wartośćSekund do zwrotu rezerwacjiSekund do zwrotu rezerwacji: 300 wartość300Wpisów w paczceWpisów w paczce: 89 wartość89Limit wysyłki recepcji (s)Limit wysyłki recepcji (s): 5 wartość5
Źródło: Opisy funkcji Webhook Outbox i Reception Events Webhook (dokumentacja produktu)

Praktyka 4–5: potwierdzenia i kolejność

Czwarta: potwierdzaj dostawę na końcu i licz na idempotentność potwierdzenia. Potwierdzenie przyjmuje status delivered lub failed z opcjonalnym opisem błędu, a potwierdzenie wpisu już doręczonego nic nie zmienia. Odbiornik może więc bezpiecznie powtórzyć potwierdzenie po utracie odpowiedzi sieciowej.

Piąta: nie zakładaj kolejności. Pobranie paczki rezerwuje do 89 wpisów atomowo, ale kolejność dostarczenia do odbiorców końcowych zależy od poller i sieci. Zdarzenia o zmianie stanu (aktualizacja grupy, potem przerwanie) odbiorca powinien porównywać po czasie zdarzenia, a nie po kolejności nadejścia.

Praktyka 6–7: odporność na błąd i obserwowalność

Szósta: błąd odbiornika nie może zatrzymać źródła. System wysyła zdarzenia recepcji asynchronicznie, z limitem 5 sekund, aby awaria webhooka nie przerywała rejestracji gościa. Odbiornik po swojej stronie powinien odpowiadać szybko i przetwarzać w tle, zamiast trzymać połączenie do końca skomplikowanej akcji.

Siódma: loguj każde zdarzenie z kluczem i wynikiem (przetworzone, pominięte jako duplikat, błąd). Bez tego nie sposób odróżnić utraty komunikatu od poprawnego odrzucenia powtórki. W integracjach z dziennikiem wymiany taki zapis powinien być odrębny od dziennika aplikacji.

Typowe błędy, które widzimy w odbiornikach

Najczęstszy błąd to deduplikacja po treści tekstu komunikatu zamiast po kluczu zdarzenia: dwa różne alarmy o tym samym tekście zostają wtedy zlane w jeden. Drugi to znacznik z zerowym czasem życia, który pozwala na ponowne przetworzenie po restarcie. Trzeci to potwierdzanie dostawy przed wykonaniem akcji, przez co nieudana akcja nigdy nie zostanie ponowiona.

Przed uruchomieniem odbiornika w środowisku produkcyjnym wyślij to samo zdarzenie dwukrotnie i sprawdź, że w kanale pojawia się jeden wpis, a w dzienniku jeden wpis o przetworzeniu i jeden o pominięciu.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Czy system gwarantuje dostarczenie dokładnie raz?

Nie. Mechanizmy ponowień dają dostarczenie co najmniej raz, więc odbiornik powinien być idempotentny.

Czym najlepiej deduplikować zdarzenia?

Kluczem złożonym z typu zdarzenia, obiektu i czasu zdarzenia. Treść tekstu nie jest dobrym kluczem.

Co, gdy odbiornik potwierdzi dostawę dwa razy?

Nic złego. Potwierdzenie wpisu już doręczonego nic nie zmienia.

Odbiornik odporny na powtórki

Przejdziemy z Twoim integratorem przez test podwójnego zdarzenia i dziennik przetwarzania.

Porozmawiajmy