webhooki

Webhooki to mechanizm automatycznych powiadomień przekazywanych między systemami w reakcji na zdarzenie.

Jak działa webhook w praktyce

Webhook to sposób przekazywania informacji o zdarzeniu z jednego systemu do drugiego bez konieczności ciągłego pytania o jego stan. System wysyłający, nazywany często nadawcą, obserwuje określone zdarzenie, na przykład utworzenie zamówienia, zmianę statusu płatności, dodanie zgłoszenia albo zakończenie zadania. Po jego wystąpieniu wykonuje żądanie HTTP do wcześniej skonfigurowanego adresu URL. System odbierający analizuje otrzymane dane i uruchamia odpowiednią akcję, na przykład aktualizuje rekord, wysyła powiadomienie lub rozpoczyna dalsze przetwarzanie.

W typowym webhooku dane są przekazywane metodą HTTP POST, najczęściej w formacie JSON. Żądanie zawiera nagłówki HTTP oraz treść opisującą zdarzenie. W zależności od konkretnej aplikacji mogą wystąpić także inne metody, formaty danych i wymagania autoryzacyjne, dlatego szczegóły zawsze wynikają z dokumentacji danego systemu. Sam webhook nie jest osobnym protokołem sieciowym, lecz wzorcem integracji wykorzystującym istniejącą komunikację HTTP lub HTTPS.

Adres odbiorczy, ładunek danych i potwierdzenie

Podstawowym elementem konfiguracji jest publicznie dostępny adres endpointu, czyli punktu aplikacji przeznaczonego do odbierania powiadomień. Nadawca kieruje pod ten adres żądanie zawierające tak zwany payload, czyli ładunek danych. Może on obejmować identyfikator zdarzenia, jego typ, czas wystąpienia oraz dane obiektu, którego dotyczy zmiana. Zawartość nie jest uniwersalna: jeden dostawca może wysyłać pełny obiekt, a inny tylko identyfikator wymagający późniejszego pobrania szczegółów przez API.

Odbiorca powinien zwrócić nadawcy poprawny kod odpowiedzi HTTP, jeżeli żądanie zostało przyjęte i przetworzone zgodnie z wymaganiami danego rozwiązania. Kody z zakresu 2xx oznaczają pomyślną obsługę żądania, natomiast błędy sieciowe, przekroczenie limitu czasu lub odpowiedzi z zakresu 4xx i 5xx mogą spowodować ponowienie dostarczenia. Reguły ponawiania zależą od konkretnej usługi. Niektóre systemy używają opóźnień rosnących między próbami, inne ograniczają liczbę powtórzeń albo zapisują nieudane zdarzenia do późniejszego ponownego uruchomienia.

Weryfikacja źródła i odporność na powtórzenia

Endpoint webhooka powinien sprawdzać, czy żądanie pochodzi od uprawnionego nadawcy. Często służy do tego wspólny sekret lub podpis kryptograficzny umieszczany w nagłówku żądania. Odbiorca oblicza podpis na podstawie otrzymanej treści i porównuje go z wartością przesłaną przez nadawcę. Weryfikację trzeba wykonywać na niezmienionym, surowym payloadzie, ponieważ jego ponowne sformatowanie przed obliczeniem podpisu może dać inny wynik. Połączenie HTTPS szyfruje transmisję między klientem a serwerem, ale samo w sobie nie potwierdza, że nadawca jest właściwym systemem.

Obsługa webhooków powinna uwzględniać możliwość wielokrotnego dostarczenia tego samego zdarzenia. Powtórzenie może wystąpić po przekroczeniu limitu czasu, utracie odpowiedzi albo chwilowej awarii odbiorcy, nawet gdy pierwsza próba faktycznie zmieniła stan aplikacji. Z tego powodu kod obsługujący webhook powinien rozpoznawać identyfikator zdarzenia lub inną jednoznaczną cechę i nie wykonywać tej samej operacji drugi raz. Praktycznym rozwiązaniem jest szybkie przyjęcie żądania, zapisanie zdarzenia do kolejki lub bazy danych oraz wykonanie cięższych działań w osobnym procesie. W logach warto rejestrować czas odebrania, typ zdarzenia, wynik walidacji i kod odpowiedzi, bez zapisywania całej treści, jeśli nie jest to potrzebne do diagnostyki.

Webhooki w aplikacjach używanych na komputerze

Na laptopie lub komputerze PC webhook zwykle nie działa bezpośrednio jako funkcja sprzętu. Jest elementem aplikacji internetowej, programu synchronizującego, panelu administracyjnego albo narzędzia automatyzującego pracę. Problemy z jego działaniem mogą wynikać z błędnego adresu endpointu, nieprawidłowego certyfikatu TLS, blokady zapory sieciowej, niedostępności serwera odbiorczego, przekroczenia limitu czasu lub niezgodności formatu danych. Podczas sprawdzania warto porównać konfigurację z dokumentacją dostawcy, przeanalizować kody HTTP i ustalić, czy żądanie dociera do aplikacji. Pomocne są także testy z narzędzi developerskich przeglądarki, dzienniki programu oraz kontrola rozwiązywania nazwy DNS.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i podzespołów, a w przypadku problemów z aplikacją korzystającą z webhooków może pomóc rozdzielić usterkę sprzętową, sieciową i programową. Diagnostyka obejmuje między innymi sprawdzenie połączenia z internetem, działania systemu operacyjnego, zapory, certyfikatów oraz poprawności uruchamiania używanego programu. Sama naprawa komputera nie zmieni konfiguracji webhooka po stronie zewnętrznej usługi, dlatego po usunięciu problemu lokalnego należy jeszcze potwierdzić poprawność adresu, uprawnień i ustawień integracji u jej dostawcy.