nieobsługiwane zdarzenie webhooka

Nieobsługiwane zdarzenie webhooka to powiadomienie o typie, którego odbiorca nie rozpoznaje i pomija bez reakcji.

Jak rozumieć nieobsługiwane zdarzenie webhooka

Webhook jest mechanizmem, w którym jeden system wysyła do drugiego powiadomienie o zmianie stanu lub wykonaniu określonej operacji. Najczęściej odbiorca udostępnia adres URL przyjmujący żądania HTTP, a nadawca przesyła metodą POST dane opisujące zdarzenie. Nieobsługiwane zdarzenie webhooka występuje wtedy, gdy żądanie dociera do odbiorcy, lecz jego typ nie jest uwzględniony w logice aplikacji. Odbiorca może poprawnie odczytać nagłówki, treść JSON i identyfikator żądania, ale nie ma zdefiniowanej reakcji na wartość pola określającego rodzaj zdarzenia.

Przykładem może być payload zawierający pole event z wartością invoice.paid, podczas gdy aplikacja zna wyłącznie zdarzenia invoice.created i invoice.failed. Taka sytuacja różni się od błędu dostarczenia webhooka. Przy błędzie dostarczenia serwer może być niedostępny, zwracać kod HTTP 500, odrzucać połączenie albo przekraczać limit czasu. Przy nieobsługiwanym zdarzeniu komunikat został odebrany, lecz program nie potrafi przypisać go do żadnego zdefiniowanego przypadku wykonania.

Rozpoznanie typu zdarzenia w odebranym żądaniu

Obsługa webhooka zwykle rozpoczyna się od weryfikacji żądania, a następnie od odczytania typu zdarzenia z nagłówka lub treści komunikatu. Konkretne nazwy pól zależą od dostawcy integracji, dlatego nie można zakładać, że każdy system używa identycznego formatu. Często spotyka się osobne pole z nazwą zdarzenia, identyfikator zdarzenia, znacznik czasu oraz obiekt zawierający dane biznesowe. Sam fakt, że treść jest poprawnym JSON-em, nie oznacza jeszcze, że aplikacja rozumie znaczenie zawartych w niej danych.

Bezpieczna implementacja powinna rozdzielać walidację składni od wyboru procedury obsługi. Najpierw sprawdza się, czy żądanie ma właściwą metodę HTTP, oczekiwany typ treści i komplet wymaganych pól. Następnie kod wybiera funkcję na podstawie rozpoznanego typu zdarzenia. Jeśli typ nie znajduje się na liście obsługiwanych wartości, program powinien odnotować ten fakt w logu wraz z nazwą zdarzenia, identyfikatorem komunikatu i czasem odebrania. Warto zapisać również informację o wersji schematu, jeżeli nadawca ją przekazuje, ponieważ pomaga ona ustalić, czy zmiana pochodzi z aktualizacji integracji.

Skutki pominięcia nieznanego webhooka

Pominięcie nieobsługiwanego zdarzenia może być prawidłową reakcją, gdy odbiorca nie potrzebuje danego rodzaju powiadomienia. Przykładowo aplikacja może korzystać wyłącznie ze zdarzeń dotyczących zakończonej płatności, a ignorować powiadomienia o zmianie opisu produktu. W takim przypadku nieznany typ nie powinien powodować awarii całego endpointu. Problem pojawia się wtedy, gdy nowe zdarzenie niesie informację konieczną do aktualizacji lokalnego stanu, wysłania powiadomienia albo wykonania kolejnego kroku procesu.

Istotne jest także poprawne dobranie odpowiedzi HTTP. W wielu integracjach kod z zakresu 2xx oznacza, że dostawca może uznać wiadomość za przyjętą i nie ponawiać wysyłki. Zwrócenie odpowiedzi sukcesu dla nieznanego zdarzenia może więc trwale zakończyć dostarczanie komunikatu, mimo że aplikacja nie wykonała oczekiwanej operacji. Z kolei odpowiedź wskazująca błąd może uruchomić ponowienia po stronie nadawcy, ale nie zawsze jest właściwa, ponieważ kolejne próby nie rozwiążą braku procedury obsługi. Decyzja powinna wynikać z dokumentacji konkretnej integracji oraz z tego, czy nieznane zdarzenie ma zostać odłożone do późniejszego rozpatrzenia, czy świadomie pominięte.

Diagnostyka logów i utrzymanie integracji webhookowej

Podczas diagnostyki warto porównać listę typów zdarzeń deklarowanych przez dostawcę z wartościami faktycznie rejestrowanymi przez endpoint. Należy sprawdzić, czy problem pojawił się po zmianie konfiguracji, aktualizacji biblioteki, wdrożeniu nowej wersji aplikacji albo włączeniu dodatkowego rodzaju powiadomień. Pomocne są logi zawierające metodę HTTP, ścieżkę endpointu, kod odpowiedzi, czas przetwarzania, identyfikator zdarzenia i wynik wyboru procedury. Nie należy zapisywać bez potrzeby całej treści komunikatu, zwłaszcza gdy może zawierać dane uwierzytelniające lub inne informacje niewymagane do analizy.

Jeżeli nieobsługiwane zdarzenia wynikają z rozszerzania interfejsu przez dostawcę, kod powinien być odporny na pojawienie się dodatkowych wartości. Nie oznacza to akceptowania dowolnego payloadu bez kontroli. Wymagane jest zachowanie weryfikacji autentyczności, poprawności struktury i ochrony przed wielokrotnym wykonaniem tego samego zdarzenia, na przykład przez zapamiętanie identyfikatora komunikatu. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, dlatego przy diagnostyce problemów z oprogramowaniem na komputerze można sprawdzić także logi aplikacji, konfigurację endpointu oraz działanie lokalnego środowiska sieciowego.