Weryfikacja podpisu webhooka

Weryfikacja podpisu webhooka to kontrola autentyczności przychodzącego żądania HTTP. Usługa, która wysyła zdarzenie, na przykład Stripe, GitHub albo system formularzy, tworzy podpis z dokładnej treści żądania i współdzielonego sekretu. Odbiorca oblicza podpis ponownie i porównuje go z wartością w nagłówku. Zgodność oznacza, że wiadomość najpewniej pochodzi od właściwego nadawcy i nie została zmieniona. Brak zgodności powinien kończyć obsługę żądania, zanim automatyzacja zapisze dane, uruchomi agenta lub wykona akcję w zewnętrznym systemie.

Webhook nie jest tym samym co zwykłe wywołanie API z kluczem. To zewnętrzna usługa inicjuje połączenie z Twoim adresem, więc endpoint jest wystawiony na internet. Ukryty URL daje tylko słabą przeszkodę, a sprawdzenie adresu IP bywa niewystarczające, ponieważ dostawcy korzystają z wielu adresów i infrastruktury pośredniej. Podpis, zwykle oparty na HMAC, pozwala potwierdzić źródło bez udostępniania sekretu w samym żądaniu. Używaj dokładnie algorytmu, nagłówka i formatu czasu opisanych przez dostawcę, zamiast wymyślać własny wariant.

Kluczowy detal to surowe ciało żądania. Podpis jest liczony dla oryginalnych bajtów payloadu, a nie dla obiektu JSON po parsowaniu i ponownym serializowaniu. Zmiana białych znaków, kolejności pól albo kodowania może spowodować, że prawidłowy podpis nie przejdzie. Dokumentacja Stripe wprost wskazuje na konieczność przekazania niezmodyfikowanego raw body do funkcji weryfikującej. Dlatego w aplikacji najpierw pobierz surowy body, zweryfikuj podpis, a dopiero potem parsuj JSON i przekazuj dane dalej.

Praktyczny przykład: formularz zapisu wysyła webhook do workflowu, który tworzy kontakt, klasyfikuje intencję przez AI i wysyła wiadomość follow-up. Bez weryfikacji osoba znająca adres endpointu może przesłać fałszywy payload z cudzym adresem e-mail albo tekstem zawierającym instrukcję dla agenta. Poprawny przepływ jest prosty: odbierz surowe żądanie, sprawdź podpis i znacznik czasu, odrzuć niezgodność kodem 401 lub 400, zapisz identyfikator zdarzenia dla idempotencji, a dopiero potem uruchom automatyzację. Agent AI nie powinien dostawać niezweryfikowanych danych jako zaufanego polecenia.

Dobra weryfikacja obejmuje też ochronę przed powtórką zdarzenia. Atakujący może przechwycić prawidłowe żądanie i spróbować wysłać je ponownie, jeśli endpoint akceptuje sam podpis bez ograniczenia czasu. Wielu dostawców dołącza timestamp do podpisywanego komunikatu. Sprawdź dozwolone okno czasowe zgodnie z ich dokumentacją oraz zachowuj identyfikator zdarzenia. Jeśli ten sam identyfikator został już obsłużony, nie twórz drugiego kontaktu, zamówienia ani follow-upu. To łączy weryfikację podpisu z idempotencją automatyzacji.

Najczęstsze błędy są banalne, ale kosztowne: użycie sekretu z innego środowiska, weryfikowanie sparsowanego zamiast surowego body, pominięcie timestampu oraz logowanie pełnego sekretu podczas diagnozy. W produkcji przechowuj sekret w zmiennych środowiskowych, nie w kodzie ani w systemie CMS. Rozdziel sekrety testowe i produkcyjne. Rotację wykonuj według procedury dostawcy, z krótkim okresem obsługi starego oraz nowego sekretu, jeśli platforma to umożliwia. W logach zapisuj identyfikator zdarzenia i wynik weryfikacji, ale nie jego pełną treść z danymi wrażliwymi.

Podpis webhooka nie rozwiązuje wszystkich problemów bezpieczeństwa. Nie sprawdza, czy sama treść biznesowa jest sensowna, czy użytkownik ma prawo wykonać akcję, ani czy prompt przekazany dalej jest bezpieczny. Po weryfikacji nadal waliduj schemat danych, ograniczaj uprawnienia integracji i wymagaj akceptacji człowieka przy kosztownych albo nieodwracalnych działaniach. Traktuj podpis jako pierwszy filtr zaufania. Dzięki niemu automatyzacja może reagować na prawdziwe zdarzenia, zamiast bezwarunkowo wykonywać wszystko, co trafi pod publiczny URL.