Webhook należy odbierać przez HTTPS, zweryfikować podpis na podstawie oryginalnej treści oraz czas wiadomości, zwalidować schemat i zapisać zdarzenie z unikalnym ID. Proszę odpowiedzieć szybko i przetworzyć je w kolejce w sposób idempotentny. Należy liczyć się z duplikatami i zmienioną kolejnością, monitorować błędy oraz okresowo uzgadniać dane krytyczne.
Webhook to wiadomość, za pomocą której jeden system informuje drugi o zdarzeniu, na przykład otrzymanej płatności, zmianie przesyłki lub nowym kontakcie. W porównaniu z regularnym sprawdzaniem stanu pozwala reagować szybko i przy mniejszej liczbie żądań. Dostarczanie przez internet nie jest jednak idealnie uporządkowaną kolejką: wiadomość może dotrzeć wielokrotnie, z opóźnieniem, równolegle lub wcale. Odbiorca musi uwzględniać te właściwości.
Bezpieczny endpoint nie może też ufać dowolnemu JSON-owi tylko dlatego, że wygląda poprawnie. Weryfikuje pochodzenie, integralność, czas, format i uprawnienia zdarzenia. Przetwarzanie oddziela szybkie przyjęcie od powolnej logiki biznesowej i zapewnia obserwowalność. Poniższy projekt sprawdzi się w WordPressie, WooCommerce, a także w samodzielnej aplikacji.
Zdefiniuj kontrakt i cykl życia zdarzenia
Należy udokumentować typy zdarzeń, wersję, unikalne ID, czas powstania, tożsamość obiektu i schemat danych. Trzeba rozróżnić, czy payload (treść wiadomości) zawiera pełny aktualny obiekt, czy jedynie powiadomienie, po którym należy wywołać API. W przypadku pełnego obiektu opóźnione starsze zdarzenie może nadpisać nowszy stan; przy kolejnym wywołaniu API trzeba z kolei obsłużyć limity i niedostępność. Wybór zależy od dostawcy i wymaganej spójności.
Zdarzenia mają status: przyjęte, zweryfikowane, oczekujące, przetworzone lub błędne. Oryginalną treść zapisuj z uwzględnieniem jej wrażliwości i ogranicz okres przechowywania. Unikalne ID chroni przed duplikatami, a ID korelacji łączy kolejne kroki. Zdefiniuj stany końcowe i przejściowe obiektu biznesowego, aby opóźniona wiadomość „płatność oczekuje” nie cofnęła już opłaconego zamówienia.
Weryfikacja podpisu i ochrona przed ponownym użyciem
Podpis należy weryfikować dokładnie według dokumentacji dostawcy, zwykle na podstawie niezmodyfikowanej treści żądania i znacznika czasu. Jeśli framework najpierw przeformatuje treść, wynikowy podpis może się różnić. Porównanie trzeba przeprowadzać w bezpieczny sposób, a nieprawidłową wiadomość odrzucić przed przetwarzaniem biznesowym. Sekret należy przechowywać w bezpiecznej konfiguracji, używać osobnych wartości dla poszczególnych środowisk i przygotować jego rotację.
Okno czasowe i rejestrowanie identyfikatorów zmniejszają ryzyko ponownego odtworzenia przechwyconej prawidłowej wiadomości. Lista dozwolonych adresów IP (allowlist) może być dodatkową warstwą, jeśli dostawca publikuje stabilne zakresy, ale nie jedynym dowodem pochodzenia. Ogranicz endpoint rozmiarem treści żądania, obsługiwanymi metodami i limitem częstotliwości. Odpowiedzi błędów nie ujawniają stack trace ani sekretów. W przypadku własnego nadawcy chroń w ten sam sposób odbiorcę i klucz podpisujący.
- HTTPS i podpis nad oryginalną treścią żądania
- Tolerancja czasowa i unikalne ID
- Oddzielone sekrety i plan rotacji
- Limit rozmiaru, metod i częstotliwości
Odpowiadajcie szybko i przetwarzajcie w kolejce
Endpoint powinien zweryfikować i trwale zapisać zdarzenie, a następnie szybko zwrócić sukces. Jeśli w ramach jednego żądania generuje dokument, wywołuje trzy API i wysyła e-mail, dostawca może uznać to za timeout i ponowić zdarzenie. Kolejka oddziela odbiór od przetwarzania, pozwala ograniczyć współbieżność i zachowuje wiadomość podczas tymczasowej awarii zależności. Potwierdzenie wysyłaj jednak dopiero po bezpiecznym zapisaniu, a nie przed nim.
Worker korzysta z operacji idempotentnej i sprawdza aktualny stan obiektu. Błąd tymczasowy ponawia z rosnącym odstępem, a trwały błąd schematu lub uprawnień przenosi do kwarantanny. Liczba prób i wiek zdarzenia mają limit. Panel administracyjny lub dashboard umożliwia bezpieczne ponowienie poprawionej wiadomości bez ręcznej zmiany bazy danych. Przy ścisłej kolejności należy przetwarzać zdarzenia sekwencyjnie dla danego obiektu lub korzystać z wersji stanu.
Przy wysyłce szanuj odbiorcę
Własny webhook wysyłaj z jasną dokumentacją, wersją i podpisem. Endpoint odbiorcy weryfikuj przy rejestracji, a wrażliwą zmianę adresu potwierdzaj. Ustaw timeout, ograniczoną liczbę prób oraz wykładniczy odstęp z losowym rozrzutem. Sukces definiuj według uzgodnionego zakresu kodów statusu. Trwałego błędu po stronie klienta nie ponawiaj w nieskończoność, ale udostępnij przyczynę właścicielowi integracji.
Każdy subskrybent ma własny sekret i możliwość wstrzymania bez wpływu na pozostałych. Loguj ID zdarzenia, cel, próbę, czas i bezpieczny wynik. Minimalizuj payload, a dane wrażliwe udostępniaj raczej poprzez uwierzytelnione kolejne wywołanie API, jeśli model na to pozwala. Przy zmianie schematu dodaj wersję i okres przejściowy; cicha niekompatybilność jest groźniejsza niż jawnie odrzucona nowa wersja.
- Oddzielny sekret dla każdego odbiorcy
- Timeout i kontrolowane ponawianie
- Wersjonowany payload z minimum danych
- Możliwość wstrzymania i ponownego dostarczenia
Testuj i uzgadniaj krytyczne dane
Testy obejmują prawidłowy i nieprawidłowy podpis, przestarzały znacznik czasu, duplikat, współbieżność, zmienioną kolejność, uszkodzony JSON, timeout i awarię zależności. Programistom należy zapewnić bezpieczny sposób ponawiania zdarzenia testowego oraz przykładowe payloady bez produkcyjnych danych osobowych. Przy lokalnym tunelu trzeba zadbać o kontrolę dostępu i wyłączyć go po teście. Test obciążeniowy sprawdzi zarówno kolejkę, jak i ochronę endpointu.
Monitoring śledzi odsetek przyjęć, weryfikacji i przetworzeń, liczbę ponowień, wiek kolejki oraz kwarantannę. Dane krytyczne należy regularnie uzgadniać przez API lub eksport, ponieważ webhook nie musi być jedynym źródłem prawdy. Jeśli zostanie wykryta rozbieżność, proces ją naprawi lub przekaże człowiekowi. Runbook wyjaśnia, gdzie znaleźć zdarzenie, jak zweryfikować stan u dostawcy i kiedy ponowienie jest bezpieczne.
Najczęstsze pytania
Jaka jest różnica między API a webhookiem?
API wywołuje się zazwyczaj, gdy klient potrzebuje danych lub wykonania akcji; webhook inicjuje dostawca w momencie zdarzenia. Często się je łączy: webhook powiadamia o zmianie, a odbiorca pobiera przez API zweryfikowany aktualny stan.
Dlaczego webhook przyszedł dwukrotnie?
Dostawca może ponowić doręczenie po przekroczeniu limitu czasu lub braku potwierdzenia, a sieć nie gwarantuje dokładnie jednej próby. Odbiorca musi używać identyfikatora zdarzenia i przetwarzania idempotentnego, zamiast zakładać pojedyncze doręczenie.
Czy endpoint powinien zawsze zwracać sukces?
Nie. Nieprawidłowy podpis lub schemat należy odrzucić z odpowiednim kodem statusu. W przypadku prawidłowego zdarzenia proszę potwierdzić odbiór dopiero po bezpiecznym zapisaniu. Konkretna odpowiedź i zasady ponawiania wynikają z dokumentacji dostawcy oraz Państwa kontraktu.
Źródła i dalsza lektura
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
