Ponowne przetwarzanie webhooków

Ponowne przetwarzanie webhooków, często nazywane webhook replay, oznacza świadome ponowne dostarczenie lub obsłużenie konkretnego zdarzenia po błędzie. Webhook jest komunikatem HTTP wysłanym przez system źródłowy, na przykład platformę płatniczą, CRM albo formularz, gdy coś się wydarzyło. Jeśli odbiorca był niedostępny, zwrócił błąd lub wykonał tylko część pracy, samo zdarzenie biznesowe nie powinno zniknąć. Replay daje możliwość wrócenia do jednej dostawy na podstawie jej identyfikatora, zamiast ręcznie odtwarzać historię z pamięci, zrzutów ekranu i luźnych logów.

Nie myl replay z automatycznym ponawianiem prób. Retry jest zwykle decyzją nadawcy bezpośrednio po błędzie i wykonuje kolejną próbę według ustalonego harmonogramu. Replay jest późniejszym, kontrolowanym działaniem: operator lub proces wybiera konkretny event, sprawdza jego status oraz uruchamia go ponownie po usunięciu przyczyny problemu. Dostawcy różnią się możliwościami. Stripe dokumentuje automatyczne próby dostawy po odpowiedzi innej niż 2xx, a GitHub udostępnia historię dostaw i mechanizmy redelivery. Własny system może zapisywać surowe, zweryfikowane zdarzenia w trwałym rejestrze i odtwarzać je z niego.

Dla solopreneura przykład jest bardzo praktyczny. Płatność za konsultację została potwierdzona, ale workflow po webhooku nie utworzył rekordu klienta i nie wysłał informacji organizacyjnej, bo CRM miał chwilową awarię. Poprawne odzyskanie sprawy nie polega na ręcznym klikaniu wszystkich kolejnych kroków. Najpierw identyfikujesz event płatności, sprawdzasz, czy płatność nadal ma właściwy status, a następnie uruchamiasz ponownie obsługę tego jednego zdarzenia. Workflow powinien rozpoznać, że opłacone zamówienie już istnieje, utworzyć brakujący rekord lub uzupełnić brakujący etap, ale nie pobrać opłaty ani nie wysłać klientowi trzech identycznych wiadomości.

Warunkiem bezpiecznego replay jest idempotencja. Ten sam event może dotrzeć więcej niż raz z powodu retry, ręcznego redelivery albo awarii po stronie odbiorcy już po wykonaniu skutku. Odbiorca powinien zapisać stabilny identyfikator dostawy lub identyfikator biznesowy i przed działaniem sprawdzić, czy efekt został już zrealizowany. Dla dostępu do produktu użyj operacji typu upsert powiązanej z identyfikatorem zamówienia. Dla wiadomości zapisz identyfikator kampanii i sprawy. Nie oznaczaj zdarzenia jako obsłużonego przed trwałym zapisem wyniku, bo po awarii stracisz możliwość odróżnienia sukcesu od częściowego wykonania.

Replay nie może omijać bezpieczeństwa. Zapisane zdarzenie musi pochodzić z zaufanego kanału i przejść weryfikację podpisu przy wejściu. Nie buduj publicznego endpointu „odtwórz webhook” przyjmującego dowolny JSON. Uprawnienie do ponowienia powinno być ograniczone, rejestrowane i dostępne tylko dla konkretnych typów zdarzeń. Przed ponowieniem odczytaj aktualny stan w źródle prawdy, gdy decyzja dotyczy płatności, zgody, anulowania lub dostępu. Stary payload może już nie opisywać aktualnej sytuacji, więc mechaniczne ponowienie bez kontroli potrafi odwrócić nowszą decyzję klienta.

Zaprojektuj prosty rejestr dostaw. Dla każdego zdarzenia zapisz identyfikator nadawcy, typ, czas odebrania, wynik weryfikacji, identyfikator sprawy biznesowej, liczbę prób, status przetwarzania i bezpieczny opis błędu. Dane wrażliwe ogranicz do minimum, ponieważ payload webhooka może zawierać dane klienta. Przy błędzie po określonej liczbie retry przenieś sprawę do kolejki błędów lub widoku wymagającego decyzji. Przycisk replay powinien pokazać, co zostanie uruchomione, kto go użył i czy poprzedni skutek już istnieje. Taki rejestr jest przydatniejszy niż sama lista odpowiedzi HTTP.

Najczęstsza pułapka to traktowanie odpowiedzi HTTP 200 jako dowodu pełnego sukcesu. Odbiorca mógł przyjąć event, a potem nie zapisać danych, nie uruchomić zadania asynchronicznego albo wykonać tylko pierwszy z kilku kroków. Druga pułapka to ręczne wysłanie starego payloadu bez identyfikatora i bez testu duplikatu. Zacznij od jednego krytycznego zdarzenia, na przykład potwierdzenia płatności lub nowego leada. Zasymuluj awarię po trwałym zapisie częściowego wyniku, uruchom replay dwa razy i sprawdź, czy stan końcowy jest jeden, kompletny oraz możliwy do wyjaśnienia w rejestrze. Dopiero wtedy rozszerzaj mechanizm na kolejne integracje.