brak odbioru webhooków

Brak odbioru webhooków to ogólne określenie usterki uniemożliwiającej systemowi przyjmowanie zewnętrznych powiadomień.

Na czym polega brak odbioru webhooków

Brak odbioru webhooków oznacza, że system wysyłający zdarzenia nie może skutecznie dostarczyć powiadomienia do wskazanego punktu końcowego HTTP. Webhook jest zwykle żądaniem POST wysyłanym na określony adres URL po wystąpieniu zdarzenia, na przykład po utworzeniu zamówienia, zmianie statusu płatności albo zakończeniu procesu w aplikacji. W treści żądania znajduje się najczęściej dokument JSON, a nagłówki określają między innymi typ danych, identyfikator zdarzenia i sposób uwierzytelnienia.

Usterka może wystąpić po stronie nadawcy, odbiorcy albo w komunikacji pomiędzy nimi. Przykładem jest nieaktualny adres endpointu, błąd rozpoznawania nazwy DNS, odrzucenie połączenia przez zaporę sieciową, nieprawidłowy certyfikat TLS, przekroczenie czasu oczekiwania lub odpowiedź HTTP wskazująca błąd. Sam fakt, że aplikacja działa w przeglądarce, nie potwierdza poprawnego odbierania webhooków, ponieważ żądania przychodzące mogą być obsługiwane przez inny proces, port, adres IP albo regułę zapory.

Droga żądania od nadawcy do endpointu

Diagnostyka zaczyna się od ustalenia, czy nadawca w ogóle próbuje wysłać zdarzenie. W jego logach należy szukać czasu wysyłki, adresu docelowego, identyfikatora zdarzenia, kodu odpowiedzi i liczby ponowień. Brak wpisu o próbie dostarczenia wskazuje na problem z konfiguracją wyzwalacza, filtrowaniem zdarzeń lub kolejką po stronie nadawcy. Jeżeli próba jest rejestrowana, ale nie ma odpowiedzi HTTP, należy sprawdzić osiągalność hosta, port HTTPS, trasę sieciową oraz działanie usługi nasłuchującej.

Odbiorca powinien rejestrować przyjęcie żądania jeszcze przed rozpoczęciem dalszego przetwarzania danych. Pozwala to rozróżnić kilka sytuacji: żądanie nie dotarło do serwera, dotarło do serwera, lecz zostało odrzucone przez warstwę pośrednią, zostało przyjęte przez aplikację, ale zakończyło się błędem podczas obsługi, albo zostało przetworzone, lecz wynik nie został poprawnie zapisany. Warto porównać znacznik czasu i identyfikator zdarzenia po obu stronach. Różnica czasu systemowego może utrudniać analizę logów, ale sama w sobie nie musi blokować odbioru webhooka.

Najczęstsze przyczyny odrzucenia powiadomień

Jedną z częstych przyczyn jest zmiana adresu endpointu bez aktualizacji konfiguracji nadawcy. Podobny skutek powoduje przekierowanie z jednego adresu URL na inny, zwłaszcza gdy nadawca nie obsługuje przekierowań dla żądań POST albo nie przekazuje przy nich pełnej treści. Problem może także wynikać z błędnego certyfikatu TLS, niedopasowanej nazwy domeny, wygaśnięcia certyfikatu lub niezgodności obsługiwanych protokołów szyfrowania. Przy połączeniach HTTPS weryfikacja certyfikatu odbywa się przed przekazaniem treści żądania do aplikacji.

Endpoint może zwracać kody HTTP 400, gdy dane są niepoprawne, 401 lub 403, gdy zawodzi uwierzytelnienie albo autoryzacja, oraz 404, gdy ścieżka nie istnieje. Kod 405 może oznaczać, że adres nie przyjmuje metody POST, a odpowiedzi z zakresu 500 wskazują na błąd po stronie serwera. Niektóre systemy ponawiają wysyłkę po odpowiedziach błędnych lub po braku odpowiedzi, lecz sposób i czas ponowień zależą od konkretnego nadawcy. Wielokrotne próby mogą doprowadzić do powielenia tego samego zdarzenia, dlatego odbiorca powinien rozpoznawać identyfikator komunikatu i stosować idempotentne przetwarzanie, czyli takie, w którym ponowne dostarczenie nie powoduje niepożądanej drugiej operacji.

Postępowanie przy przywracaniu odbioru

Praktyczna analiza powinna objąć konfigurację adresu URL, metodę żądania, wymagane nagłówki, format danych, mechanizm podpisu lub tokenu oraz reguły dostępu na zaporze i serwerze HTTP. Następnie należy ustalić, czy żądanie kończy się na warstwie DNS, TLS, serwerze proxy, routerze aplikacyjnym czy właściwym module odbierającym webhooki. Jeżeli serwer otrzymuje żądania, ale aplikacja ich nie widzi, przyczyną może być błędna ścieżka routingu, filtr nagłówków, limit rozmiaru treści, odrzucenie nieobsługiwanego typu MIME albo wyjątek występujący przed zapisaniem zdarzenia.

Po zmianie konfiguracji należy wykonać kontrolne zdarzenie i prześledzić je na całej trasie: od utworzenia po stronie nadawcy, przez zestawienie połączenia, aż do potwierdzenia odbioru i zapisania danych. Odpowiedź potwierdzająca powinna być zwracana dopiero wtedy, gdy system ma pewność, że komunikat został przyjęty zgodnie z przyjętym modelem przetwarzania. Jeżeli dalsza obsługa jest asynchroniczna, bezpieczniejszy jest szybki zapis komunikatu do kolejki lub trwałego magazynu i dopiero potem odpowiedź dla nadawcy. W przypadku naprawy laptopa lub komputera PC diagnostyka może obejmować sprawdzenie systemu, konfiguracji sieciowej, lokalnych reguł zapory, certyfikatów oraz działania zainstalowanej aplikacji, o ile problem wynika z nieprawidłowej pracy urządzenia lub jego oprogramowania.