webhook

Webhook to mechanizm automatycznego powiadamiania systemu docelowego o zdarzeniu przez wywołanie wskazanego adresu.

Webhook jako powiadomienie wywoływane przez zdarzenie

Webhook to mechanizm komunikacji, w którym jeden system wysyła powiadomienie do drugiego systemu natychmiast po wystąpieniu określonego zdarzenia. Powiadomienie jest zwykle realizowane jako żądanie HTTP skierowane do wcześniej skonfigurowanego adresu URL. System odbierający nie musi stale pytać systemu źródłowego, czy pojawiły się nowe dane. Zamiast tego system źródłowy sam inicjuje przekazanie informacji, gdy zajdzie wskazany warunek, na przykład utworzenie zamówienia, zmiana statusu płatności, dodanie wpisu albo zakończenie zadania.

Adres odbierający webhook nazywa się często endpointem. Musi on być dostępny dla systemu wysyłającego i obsługiwać ustaloną metodę HTTP, najczęściej POST. W treści żądania przekazywane są dane zdarzenia, zazwyczaj w formacie JSON. Przykładowy komunikat może zawierać identyfikator obiektu, typ zdarzenia, czas jego wystąpienia oraz aktualny status. Webhook nie jest osobnym protokołem sieciowym, lecz sposobem wykorzystania istniejącej komunikacji HTTP do przekazywania zdarzeń między aplikacjami.

Budowa żądania i rozpoznawanie zdarzeń

Żądanie webhooka może zawierać nagłówki HTTP opisujące format danych, identyfikator nadawcy lub sposób uwierzytelnienia. Typowy nagłówek Content-Type: application/json informuje odbiorcę, że treść ma postać JSON. W samym JSON-ie można umieścić pole określające rodzaj zdarzenia, na przykład event, oraz obiekt data z właściwymi informacjami. Dokładne nazwy pól nie są uniwersalne i zależą od dokumentacji konkretnej aplikacji albo usługi.

Endpoint powinien sprawdzać, czy odebrane żądanie ma poprawną strukturę i pochodzi od uprawnionego nadawcy. Stosuje się między innymi token umieszczony w nagłówku, podpis kryptograficzny obliczany na podstawie treści żądania albo ograniczenie dostępu do znanych adresów sieciowych. Sam fakt, że żądanie dotarło na właściwy adres, nie potwierdza jeszcze jego autentyczności. W praktycznej implementacji należy również sprawdzać metodę HTTP, typ zawartości, rozmiar komunikatu oraz to, czy identyfikator zdarzenia nie został już wcześniej przetworzony.

Obsługa opóźnień, powtórzeń i błędów

Webhook jest komunikacją zależną od sieci, dlatego dostarczenie powiadomienia nie zawsze kończy się sukcesem za pierwszym razem. Odbiorca może być chwilowo niedostępny, odpowiedź może przekroczyć limit czasu, a po drodze może wystąpić błąd DNS, połączenia TLS albo serwera HTTP. Nadawca często ponawia wysyłkę, gdy otrzyma kod błędu lub nie otrzyma odpowiedzi w wymaganym czasie. Z tego powodu endpoint powinien być odporny na wielokrotne dostarczenie tego samego zdarzenia.

W tym celu stosuje się idempotentną obsługę, czyli takie przetwarzanie, przy którym ponowienie tego samego komunikatu nie powoduje wielokrotnego wykonania skutku ubocznego. Aplikacja może zapisać identyfikator odebranego zdarzenia przed rozpoczęciem operacji albo wykorzystać klucz idempotencji przekazany przez nadawcę. Po poprawnym przyjęciu żądania endpoint zazwyczaj zwraca odpowiedź z klasy kodów 2xx, na przykład 200 OK albo 202 Accepted. Kod 202 może oznaczać, że komunikat został przyjęty do dalszego przetwarzania asynchronicznego, ale sama operacja nie została jeszcze zakończona.

Ważne jest rozdzielenie przyjęcia komunikatu od długotrwałej pracy wykonywanej na jego podstawie. Endpoint może szybko zweryfikować podpis, zapisać zdarzenie i przekazać je do kolejki wewnętrznej, a następnie zwrócić odpowiedź. Ogranicza to ryzyko przekroczenia limitu czasu po stronie nadawcy. Logi powinny rejestrować identyfikator zdarzenia, typ komunikatu, wynik weryfikacji oraz rezultat przetwarzania. Nie należy jednak bez potrzeby zapisywać w logach całej treści zawierającej dane formularzy, tokeny lub inne informacje, które nie są potrzebne do diagnozowania działania mechanizmu.

Webhook w aplikacjach używanych na komputerze

Webhook może łączyć aplikację uruchomioną na laptopie lub komputerze PC z usługą działającą w sieci. Przykładem jest program, który po zakończeniu synchronizacji wysyła zdarzenie do panelu, automatyzacji albo innego systemu. W przypadku aplikacji działającej wyłącznie lokalnie problemem może być brak publicznie dostępnego adresu URL. Sam adres localhost wskazuje komputer, na którym wykonano żądanie, więc zdalny nadawca nie dotrze tą drogą do programu uruchomionego na innym urządzeniu. Konieczne jest wtedy użycie odpowiednio skonfigurowanego punktu pośredniczącego albo rozwiązania przewidzianego przez konkretną aplikację.

Podczas diagnozy problemów z webhookiem sprawdza się kolejno adres endpointu, rozwiązywanie nazwy DNS, połączenie HTTPS, certyfikat TLS, metodę HTTP, nagłówki, format JSON i odpowiedź serwera. Należy także porównać czas wysłania zdarzenia z czasem jego odebrania oraz ustalić, czy nadawca nie ponawia komunikatu po zbyt wolnej odpowiedzi. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, dlatego w przypadku problemów z aplikacją obsługującą webhook można rozpocząć od sprawdzenia systemu, połączenia sieciowego i konfiguracji programu na urządzeniu.