duplikaty zdarzeń webhooka

Duplikaty zdarzeń webhooka to usterka, w której to samo powiadomienie HTTP zostaje przetworzone więcej niż jeden raz.

Na czym polega powielone zdarzenie webhooka

Duplikaty zdarzeń webhooka powstają wtedy, gdy odbiorca traktuje więcej niż jedną wiadomość HTTP jako nowe zdarzenie, chociaż wszystkie wiadomości opisują ten sam fakt w systemie nadawcy. Webhook jest mechanizmem powiadamiania: aplikacja źródłowa wysyła żądanie HTTP, zwykle metodą POST, do wskazanego adresu URL. Treść żądania zawiera dane zdarzenia, na przykład identyfikator płatności, zmianę statusu zamówienia, utworzenie użytkownika albo zakończenie zadania. Samo ponowne wysłanie żądania nie musi oznaczać, że w systemie źródłowym wystąpiło nowe zdarzenie.

Powtórzenie może wynikać z normalnej pracy mechanizmu dostarczania. Jeżeli nadawca nie otrzyma odpowiedzi potwierdzającej odbiór w wymaganym czasie, może ponowić wysyłkę. Taka sytuacja występuje między innymi po przekroczeniu limitu czasu, błędzie połączenia, chwilowej niedostępności serwera odbiorcy albo przerwaniu połączenia po stronie klienta. Nadawca może wysłać zdarzenie ponownie nawet wtedy, gdy odbiorca rozpoczął już jego przetwarzanie, lecz odpowiedź HTTP nie dotarła do nadawcy.

Dlaczego samo sprawdzenie numeru żądania nie wystarcza

Rozpoznawanie duplikatów wymaga ustalenia, który element wiadomości jednoznacznie identyfikuje zdarzenie. W wielu systemach znajduje się on w nagłówku HTTP, na przykład jako identyfikator dostawy, albo w treści JSON jako identyfikator zdarzenia. Nie można jednak zakładać, że każdy dostawca webhooków stosuje tę samą nazwę pola, ten sam format identyfikatora lub tę samą regułę ponawiania. Numer połączenia, adres IP nadawcy, znacznik czasu odebrania oraz numer żądania po stronie serwera nie są wystarczającą podstawą do stwierdzenia, że wiadomość jest nowa albo powtórzona.

Znacznik czasu jest szczególnie zawodny jako jedyny mechanizm deduplikacji. Dwa różne zdarzenia mogą mieć bardzo zbliżony czas utworzenia, a to samo zdarzenie może zostać dostarczone po dłuższej przerwie. Również porównywanie całej treści żądania może prowadzić do błędów, ponieważ dostawca może zmienić kolejność pól JSON, dodać pole techniczne albo odświeżyć znacznik wysyłki przy ponowieniu. Najbezpieczniej korzystać z identyfikatora nadanego przez system źródłowy, zgodnie z jego dokumentacją, i zapisywać informację o obsłużeniu tego identyfikatora.

Ważne jest także odróżnienie duplikatu od dwóch prawidłowych zdarzeń dotyczących tego samego obiektu. Przykładowo, zamówienie może najpierw przejść do stanu „opłacone”, a następnie do stanu „zrealizowane”. Oba komunikaty mogą wskazywać ten sam numer zamówienia, ale nie są tym samym zdarzeniem. Deduplikacja powinna więc uwzględniać identyfikator zdarzenia, a nie tylko identyfikator obiektu biznesowego.

Idempotentne przetwarzanie i kontrola skutków ubocznych

Podstawową ochroną przed duplikatami jest idempotencja obsługi webhooka. Operacja jest idempotentna wtedy, gdy wielokrotne przetworzenie tej samej wiadomości prowadzi do takiego samego stanu końcowego jak przetworzenie jej jeden raz. W praktyce odbiorca zapisuje identyfikator zdarzenia w trwałym magazynie danych i przed wykonaniem operacji sprawdza, czy identyfikator był już obsłużony. Sprawdzenie i zapis powinny być zabezpieczone przed równoczesnym wykonaniem przez dwa procesy, na przykład przez unikalne ograniczenie w bazie danych albo inną atomową operację właściwą dla użytego magazynu.

Sam wpis o odebraniu wiadomości nie powinien być oznaczany jako zakończony przed wykonaniem wymaganej logiki. W przeciwnym razie awaria pomiędzy zapisem identyfikatora a właściwą aktualizacją danych może spowodować utratę zdarzenia. Z drugiej strony ponowienie całej operacji bez kontroli może wykonać skutek uboczny kilka razy: utworzyć podwójną fakturę, naliczyć płatność, wysłać wielokrotnie wiadomość, zwiększyć licznik albo powtórnie uruchomić kosztowne zadanie.

Bezpieczny przepływ powinien rozdzielać przyjęcie wiadomości, weryfikację jej autentyczności, zapis stanu przetwarzania oraz wykonanie skutku biznesowego. Jeżeli obsługa jest przekazywana do kolejki, także zadanie w kolejce musi być odporne na ponowienie, ponieważ system kolejkowy może dostarczyć je więcej niż jeden raz. Przydatne są stany takie jak „odebrane”, „w trakcie”, „zakończone” i „błąd”, lecz ich znaczenie musi być jasno określone. W szczególności trzeba rozstrzygnąć, czy wiadomość zakończona błędem może zostać bezpiecznie wykonana ponownie oraz kiedy nadawca powinien otrzymać odpowiedź HTTP potwierdzającą przyjęcie.

Jak rozpoznać i ograniczyć duplikaty webhooka

Diagnostyka zaczyna się od porównania logów nadawcy i odbiorcy. Należy zestawić identyfikator zdarzenia, czas utworzenia, czas dostarczenia, kod odpowiedzi HTTP, czas odpowiedzi, liczbę prób oraz wynik obsługi. Jeżeli kilka żądań ma ten sam identyfikator zdarzenia, prawdopodobnie są ponowieniami. Jeżeli identyfikatory są różne, lecz odnoszą się do tego samego obiektu i podobnego stanu, może chodzić o osobne zdarzenia albo o błąd po stronie nadawcy. Warto również sprawdzić, czy różne instancje aplikacji nie zapisują zdarzeń w odmiennych bazach lub z innymi kluczami deduplikacji.

W logach powinny być widoczne co najmniej: identyfikator zdarzenia, identyfikator obiektu, wynik weryfikacji podpisu, decyzja „nowe” albo „duplikat”, stan przetwarzania oraz przyczyna ewentualnego odrzucenia. Nie należy zapisywać wprost pełnych sekretów podpisujących ani danych, które nie są potrzebne do odtworzenia przebiegu. Z punktu widzenia diagnostyki ważne jest jednak zachowanie spójnego identyfikatora korelacyjnego, aby można było prześledzić jedno dostarczenie od wejścia HTTP do końcowej operacji.

Jeżeli duplikaty już występują, trzeba najpierw ustalić, czy powtarza się samo żądanie, czy również skutek biznesowy. Powtórzone żądanie z pominiętym skutkiem może być normalnym zachowaniem poprawnie zaprojektowanego odbiorcy. Wielokrotny skutek oznacza brak idempotencji, nieatomowy zapis identyfikatora, błędną obsługę wyścigu między procesami albo nieprawidłowe rozróżnianie zdarzeń. Diagnostyka i naprawa takiego problemu wymaga prześledzenia konfiguracji webhooka, kodu odbiorcy, zapisów w bazie danych i logów aplikacji, ponieważ sam komunikat o ponownej dostawie nie wskazuje jeszcze miejsca usterki.