Stosuj webhooki z podpisem lub tokenem weryfikacyjnym.

Webhooki z podpisem lub tokenem weryfikacyjnym chronią przed przyjęciem powiadomień z niezaufanego źródła.

Webhook jako komunikat przychodzący do aplikacji

Webhook to żądanie HTTP wysyłane automatycznie przez jeden system do adresu URL udostępnionego przez drugi system. Nadawca może w ten sposób przekazać informację o utworzeniu zamówienia, zmianie statusu, zakończeniu płatności albo wystąpieniu zdarzenia w aplikacji. Odbiorca nie powinien jednak uznawać każdego żądania wysłanego na publiczny adres za prawdziwe powiadomienie. Sam fakt, że komunikat dotarł metodą HTTPS, potwierdza szyfrowanie połączenia w określonym momencie, ale nie potwierdza tożsamości systemu, który wysłał żądanie.

Podpis lub token weryfikacyjny dodaje do webhooka dodatkowy mechanizm uwierzytelnienia. Odbiornik sprawdza wtedy nie tylko format danych, lecz także to, czy komunikat został wygenerowany przez podmiot znający ustalony sekret albo posiadający ważny token. Żądanie, które nie zawiera wymaganego nagłówka, ma niepoprawny podpis lub przedstawia wygasły token, powinno zostać odrzucone przed wykonaniem operacji biznesowej.

Podpis HMAC i prawidłowe sprawdzanie treści żądania

Popularnym rozwiązaniem jest podpis HMAC obliczany na podstawie surowego ciała żądania oraz wspólnego sekretu znanego nadawcy i odbiorcy. Nadawca oblicza wartość przy użyciu funkcji skrótu, na przykład HMAC-SHA-256, a następnie umieszcza wynik w nagłówku HTTP. Odbiorca pobiera dokładnie te same bajty ciała żądania, oblicza własny wynik i porównuje go z wartością otrzymaną w nagłówku.

Kolejność czynności ma znaczenie. Weryfikację należy wykonać przed przekształceniem JSON-a, ponieważ formatowanie, zmiana kolejności elementów, normalizacja znaków lub automatyczne usunięcie białych znaków może zmienić dane użyte do obliczenia podpisu. Porównanie powinno być wykonane funkcją odporną na ataki czasowe, a nie zwykłym operatorem porównania napisów. Sekret nie powinien być zapisywany w kodzie źródłowym ani zwracany w komunikatach błędów.

W praktycznej implementacji warto rozdzielić nagłówek z identyfikatorem algorytmu, znacznik czasu i właściwy podpis. Przykładowy podpis może obejmować ciąg złożony ze znacznika czasu oraz surowego ciała żądania. Odbiorca sprawdza wówczas również, czy znacznik mieści się w dopuszczalnym oknie czasowym. Chroni to przed ponownym wysłaniem przechwyconego, wcześniej poprawnego żądania, czyli atakiem replay.

Token weryfikacyjny, rotacja sekretów i obsługa błędów

Token weryfikacyjny może być przekazywany w nagłówku HTTP, a w niektórych integracjach jest ustalonym sekretem używanym do potwierdzenia konfiguracji adresu webhooka. Odbiorca powinien sprawdzić obecność tokena, jego dokładną wartość, przewidywany format oraz — jeżeli token ma czas życia — termin ważności. Token umieszczony w adresie URL może trafić do historii serwera proxy, narzędzi monitorujących albo logów przeglądarki, dlatego bezpieczniejszym miejscem jest zazwyczaj nagłówek.

Warto zaplanować zmianę sekretu bez przerywania dostaw. Podczas rotacji odbiornik może przez krótki, kontrolowany czas akceptować aktywny sekret oraz poprzedni sekret, a następnie wyłączyć stary klucz. Każdy sekret powinien mieć jasno określone zastosowanie i nie powinien być współdzielony między niepowiązanymi integracjami. Logi mogą zawierać identyfikator zdarzenia, kod odpowiedzi i przyczynę odrzucenia, ale nie powinny zawierać pełnego tokena, sekretu ani podpisu pozwalającego odtworzyć dane uwierzytelniające.

Nieudana weryfikacja powinna zakończyć się odpowiedzią HTTP 4xx, bez uruchamiania dalszego przetwarzania. Po poprawnej weryfikacji aplikacja nadal powinna kontrolować schemat danych, typy pól, identyfikator zdarzenia i możliwość jego ponownego wystąpienia. Podpis potwierdza pochodzenie i integralność komunikatu, lecz nie gwarantuje, że jego zawartość jest logiczna dla konkretnej aplikacji. Obsługa powtórzeń wymaga idempotencji, na przykład zapamiętania identyfikatora już obsłużonego zdarzenia.

Kontrola punktu odbioru webhooków na komputerze

Adres webhooka powinien wskazywać konkretną trasę aplikacji, która przyjmuje tylko oczekiwane metody HTTP i ogranicza rozmiar żądania. Usługa powinna odrzucać nieobsługiwane typy treści, nieznane schematy danych oraz żądania przekraczające ustalony limit. HTTPS chroni transmisję przed odczytem i modyfikacją podczas przesyłania, natomiast podpis lub token pozwala sprawdzić, czy komunikat pochodzi od zaufanego nadawcy. Oba mechanizmy pełnią więc różne funkcje i nie zastępują się wzajemnie.

Podczas diagnostyki warto sprawdzić, czy aplikacja rzeczywiście odczytuje surowe ciało żądania przed parsowaniem, czy używa właściwego sekretu oraz czy zegar systemowy jest poprawnie ustawiony, gdy podpis zawiera znacznik czasu. Należy też zweryfikować kody odpowiedzi, ponowienia wysyłane przez dostawcę oraz zachowanie programu po odebraniu tego samego identyfikatora zdarzenia. Błędna konfiguracja może powodować zarówno odrzucanie prawidłowych powiadomień, jak i przyjmowanie żądań pozbawionych uwierzytelnienia.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i podzespołów, a przy problemach z aplikacją można dodatkowo sprawdzić konfigurację programu, dostępność połączenia sieciowego oraz lokalne logi odpowiedzialne za odbiór powiadomień. W przypadku integracji webhook należy zachować ostrożność przy udostępnianiu sekretów i przekazać serwisantowi jedynie informacje potrzebne do odtworzenia problemu, bez ujawniania aktywnych tokenów.