Co zrobić, gdy automatyzacja nie odbierze zdarzenia? Webhooki, ponowienia i kontrola duplikatów

Gdy automatyzacja nie odbierze zdarzenia, potrzebujesz nie tylko przycisku „ponów”. Potrzebujesz sposobu wykrycia braku, sprawdzenia, czy operacja nie została już wykonana, oraz osoby, która zareaguje na błąd. Bez tych ustaleń ponowienie może naprawić problem albo stworzyć drugi.

Wyobraźmy sobie hipotetyczny sklep: płatność za zamówienie została przyjęta, ale integracja nie może połączyć się z aplikacją realizującą zamówienia. Pracownik widzi opłacone zamówienie, którego nie ma w systemie realizacji. Po wznowieniu połączenia trzeba je przekazać, ale najpierw sprawdzić, czy wcześniejsza próba nie utworzyła już zlecenia mimo braku odpowiedzi.

Ten sam problem może wystąpić przy przesyłaniu zapytań do CRM. Porządkowanie danych z formularza za pomocą reguł lub AI rozwiązuje inne zadanie niż niezawodne dostarczenie ich do systemu. Poprawnie uporządkowane zgłoszenie nadal może utknąć po drodze.

Czym jest webhook i gdzie może wystąpić błąd?

Webhook to powiadomienie wysyłane przez jeden system do drugiego, gdy wystąpi określone zdarzenie. Przykładowo system płatności informuje integrację o zmianie statusu płatności. Odbiorca analizuje wiadomość i uruchamia dalszy proces.

W typowym przepływie występują cztery elementy: system źródłowy, adres odbierający webhook, mechanizm przetwarzania oraz aplikacja docelowa. Błąd może pojawić się na każdym etapie:

• Wysyłka: nadawca nie może połączyć się z odbiorcą albo nie dostaje odpowiedzi na czas.
• Odbiór: serwer odbiorcy działa, ale nie potrafi zweryfikować lub zapisać wiadomości.
• Przetwarzanie: wiadomość została przyjęta, lecz zadanie w kolejce zakończyło się błędem.
• Operacja docelowa: aplikacja realizująca zadanie jest niedostępna albo wykonała operację, ale odpowiedź nie dotarła do integracji.

Ostatni przypadek jest szczególnie kłopotliwy. Brak odpowiedzi nie oznacza jeszcze, że nic się nie wydarzyło. Jeśli aplikacja utworzyła zlecenie, a połączenie zerwało się przed potwierdzeniem, ponowne wysłanie żądania może utworzyć kolejne.

Czy dostawca sam ponowi nieudaną dostawę?

To zależy od konkretnej usługi. Stripe opisuje automatyczne ponawianie nieudanych dostaw webhooków. Z kolei GitHub nie ponawia nieudanych dostaw automatycznie. Udostępnia historię dostaw oraz możliwości ich ponownego wysłania, ale mechanizm wykrywania i ponawiania trzeba zaplanować.

Nawet gdy dostawca ponawia wiadomości, nie oznacza to, że odzyska każdą operację biznesową. Dostawca widzi przede wszystkim odpowiedź odbiorcy webhooka. Jeśli odbiorca potwierdził przyjęcie, a późniejsza praca w tle się nie udała, ponowienie tej pracy należy już do integracji.

Przed uruchomieniem integracji zapytaj dostawcę, jak długo przechowuje historię, kiedy uznaje dostawę za nieudaną, czy ponawia ją automatycznie i czy ręczne ponowienie może nakładać się na automatyczne. Nie przenoś zasad Stripe ani GitHuba na system sklepu czy CRM bez sprawdzenia ich dokumentacji.

Dlaczego ta sama operacja może wykonać się dwa razy?

Powtórna dostawa nie musi oznaczać awarii. Nadawca mógł nie otrzymać potwierdzenia, mimo że odbiorca zapisał wiadomość. Wiadomości mogą też dotrzeć w innej kolejności niż ta, w której powstały. Dokumentacja Stripe zaleca obsługę duplikatów i wskazuje, że kolejność zdarzeń nie jest gwarantowana.

Dlatego warto rozróżnić dwa identyfikatory:

• Identyfikator zdarzenia pomaga rozpoznać ponowną dostawę tej samej wiadomości. Jeśli zdarzenie zapisano wcześniej, odbiorca nie powinien bezwarunkowo uruchamiać go drugi raz.
• Identyfikator operacji biznesowej odnosi się do działania, które ma zostać wykonane, na przykład utworzenia realizacji dla konkretnego zamówienia. Pomaga również wtedy, gdy dwa różne zdarzenia dotyczą tej samej operacji.

W hipotetycznym sklepie kluczem operacji może być połączenie identyfikatora zamówienia z rodzajem działania, na przykład „utwórz realizację”. Trzeba jednak dopasować regułę do procesu: jedno zamówienie może zgodnie z zasadami firmy wymagać kilku oddzielnych realizacji. Wtedy sam numer zamówienia byłby zbyt ogólny.

Co oznacza idempotencja w praktyce?

Operacja jest idempotentna, jeśli jej ponowne wykonanie nie powoduje dodatkowego niepożądanego skutku. W integracji chodzi na przykład o to, aby kolejne próby utworzenia tej samej realizacji nie tworzyły kolejnych zleceń.

Najbezpieczniej wykorzystać mechanizm zapobiegania duplikatom oferowany przez system docelowy, jeśli jest dostępny i pasuje do procesu. Integracja przekazuje wtedy stabilny klucz operacji także przy ponowieniach. Jeżeli system docelowy nie ma takiej funkcji, potrzebna jest dodatkowa kontrola, na przykład wyszukanie realizacji po identyfikatorze zewnętrznym.

Samo sprawdzenie „czy istnieje?” przed utworzeniem nie zawsze wystarczy: dwa równoległe zadania mogą jednocześnie nie znaleźć rekordu i oba go utworzyć. Warto omówić z wykonawcą zabezpieczenie przed równoczesnym przetwarzaniem oraz ograniczenia systemu docelowego. Gdy wynik pozostaje niepewny, zadanie powinno trafić do weryfikacji zamiast być ponawiane w ciemno.

Jak zaprojektować bezpieczną obsługę webhooka?

Praktyczny schemat oddziela szybkie przyjęcie wiadomości od wykonania właściwej pracy. Nie daje gwarancji braku awarii, ale pozwala ustalić, na którym etapie wystąpił problem i jak go odzyskać.

1. Zweryfikuj nadawcę. Sprawdź autentyczność wiadomości zgodnie z mechanizmem danego dostawcy, na przykład przez weryfikację podpisu. Nie wykonuj operacji na podstawie dowolnego żądania wysłanego na publiczny adres.
2. Sprawdź podstawowe dane i zapisz zdarzenie trwale. Zapis powinien pozwolić odnaleźć identyfikator, czas odbioru i dane potrzebne do dalszej pracy. Warto zadbać, by utworzenie wpisu do przetworzenia nie mogło zostać pominięte po potwierdzeniu odbioru.
3. Potwierdź odbiór. Odpowiedź o sukcesie powinna oznaczać, że wiadomość została bezpiecznie przyjęta do dalszej obsługi, a niekoniecznie że zamówienie już zrealizowano. Jeśli trwały zapis się nie udał, nie należy potwierdzać sukcesu.
4. Przetwarzaj w tle. Osobne zadanie odczytuje zapisane zdarzenie, sprawdza stan i wykonuje operację w systemie docelowym.
5. Zapisz wynik. Zachowaj status operacji oraz identyfikator utworzonego obiektu lub informację, że wynik wymaga wyjaśnienia.

GitHub wymaga odpowiedzi na webhook w ciągu 10 sekund i wskazuje kolejkę jako sposób na obsługę pracy poza żądaniem. Ten limit dotyczy GitHuba, nie wszystkich dostawców. Dla własnej integracji trzeba sprawdzić właściwy czas oraz sposób sygnalizowania błędów.

Weryfikacja podpisu i trwały zapis rozwiązują różne problemy: pierwsza pomaga odrzucić nieautentyczne żądanie, drugi pozwala odzyskać przyjętą pracę po awarii. W obu przypadkach wykonawca powinien sprawdzić szczegóły w dokumentacji źródła zdarzeń.

Kiedy ponawiać automatycznie, a kiedy zatrzymać zadanie?

Nie każdy błąd zniknie po kolejnej próbie. Chwilowa niedostępność usługi może uzasadniać automatyczne ponowienie po przerwie. Błędna konfiguracja, brak uprawnień lub nieprawidłowe dane wymagają raczej poprawki. W przypadku nieznanego wyniku operacji najpierw trzeba ustalić, czy system docelowy już ją wykonał.

Ustal z wykonawcą limit prób, odstępy między nimi i sposób postępowania po wyczerpaniu limitu. Zwiększanie odstępów pomaga nie zasypywać niedostępnego systemu żądaniami. Zadanie, którego nie udało się przetworzyć, powinno pozostać widoczne jako wymagające interwencji, a nie znikać z kolejki bez śladu.

Przykładowa decyzja dla zamówienia może wyglądać tak:

1. Integracja nie otrzymała odpowiedzi na żądanie utworzenia realizacji.
2. Sprawdza po identyfikatorze operacji, czy realizacja istnieje.
3. Jeśli istnieje i dane się zgadzają, zapisuje jej identyfikator zamiast tworzyć kolejną.
4. Jeśli wiarygodnie potwierdzono brak realizacji, ponawia operację zgodnie z ustalonym limitem.
5. Jeśli nie da się sprawdzić wyniku albo dane są sprzeczne, wstrzymuje zadanie i wysyła alert do osoby odpowiedzialnej.

To hipotetyczny schemat. Jego wykonalność zależy od tego, czy aplikacja docelowa pozwala wyszukać operację i jak szybko udostępnia aktualny stan. Jeśli nie daje wiarygodnej odpowiedzi, potrzebna może być ręczna kontrola lub zmiana projektu integracji.

Jak wykryć brakujące zdarzenia?

Monitoring powinien obejmować zarówno nieudane dostawy, jak i zadania, które utknęły po przyjęciu webhooka. Sam komunikat „serwer działa” nie wystarczy. Integracja może odpowiadać poprawnie, a jednocześnie mieć narastającą kolejkę błędów.

W logach i panelu operacyjnym przydają się: identyfikator zdarzenia i operacji, czas odbioru, status, liczba prób oraz kategoria błędu. Zakres danych warto ograniczyć do potrzeb diagnostycznych. Hasła, klucze i pełna treść wiadomości z danymi klientów nie powinny trafiać do logów bez uzasadnienia i odpowiednich zabezpieczeń.

Alert musi mieć odbiorcę

Ustal, kto dostaje powiadomienie, jak szybko ma zareagować i kto przejmuje sprawę podczas nieobecności tej osoby. Innej reakcji może wymagać pojedynczy błąd rozwiązany automatycznie, a innej zadania po wyczerpaniu prób lub rosnące opóźnienie kolejki.

Dobry alert wskazuje proces, skalę problemu i miejsce sprawdzenia szczegółów. Procedura powinna też mówić, kto może wznowić zadanie i jakie kontrole wykonać przed ponowieniem. Jeśli potrzebujesz uporządkować taki zakres przed wyborem rozwiązania, możesz omówić go podczas konsultacji technologicznej.

Porównuj stan ze źródłem

Nie wszystkie braki da się wykryć z logów odbiorcy. Jeśli wiadomość w ogóle do niego nie dotarła, może nie być tam żadnego wpisu. Dlatego dla ważnych procesów warto okresowo porównywać dane w systemie źródłowym ze stanem w systemie docelowym. W przykładzie sklepu byłaby to lista opłaconych zamówień zestawiona z listą realizacji.

Najpierw ustal, które stany rzeczywiście powinny mieć swoje odpowiedniki: anulowanie, zwrot lub podział zamówienia mogą zmieniać oczekiwany wynik. Rozbieżności powinny tworzyć listę do wyjaśnienia, a ich automatyczne uzupełnianie musi podlegać tym samym kontrolom duplikatów co zwykłe ponowienie.

Ma to znaczenie również ze względu na ograniczenia historii dostaw. GitHub pozwala ponownie dostarczyć webhooki z ostatnich trzech dni. Po dłuższej awarii samo ponowienie dostaw może nie wystarczyć. Dostępny zakres i sposób odtworzenia danych w innych usługach trzeba sprawdzić osobno.

Co ustalić z wykonawcą przed uruchomieniem?

• Wykrywanie: gdzie widać nieudane dostawy, błędy kolejki i zadania o nieznanym wyniku? Jak wykryjemy zdarzenie, które w ogóle nie dotarło?
• Ponowienia: które błędy można ponawiać automatycznie, ile razy i w jakich odstępach? Co dzieje się po wyczerpaniu prób?
• Duplikaty: jaki jest identyfikator zdarzenia, a jaki klucz operacji biznesowej? Czy system docelowy obsługuje ten klucz i równoczesne żądania?
• Odzyskiwanie: jak długo dostępna jest historia, jak porównać dane ze źródłem i kto może uruchomić ponowne przetwarzanie?
• Odpowiedzialność: kto odbiera alerty, w jakich godzinach i kto decyduje o ręcznej interwencji?
• Testy: jak sprawdzimy brak odpowiedzi, ponowną dostawę, zmianę kolejności, awarię po zapisie oraz niepewny wynik operacji docelowej?
• Koszty: co obejmuje wykonanie integracji, a co jest osobnym kosztem serwera, monitoringu, obsługi alertów i usług dostawców?

Wycena zależy od procesu i używanych systemów. Przykładowo cennik Stripe opisuje opłaty za usługi płatnicze, a nie koszt zbudowania i utrzymania całej integracji. Przed wyborem narzędzi sprawdź aktualne warunki oraz dostępność potrzebnych funkcji. Najważniejszym rezultatem rozmowy z wykonawcą powinien być zapisany plan: co wykrywamy, jak bezpiecznie odzyskujemy pracę i kto reaguje, gdy automatyczne próby nie wystarczą.