Co to jest webhook i jak działa?

Klient składa zamówienie i przechodzi do płatności. Kilkanaście sekund później operator płatności potwierdza transakcję, sklep zmienia status zamówienia, system magazynowy rezerwuje produkty, a klient otrzymuje wiadomość o rozpoczęciu realizacji.

Żaden pracownik nie musi w tym czasie odświeżać panelu operatora płatności i ręcznie sprawdzać, czy pieniądze wpłynęły.

System płatniczy sam wysyła informację do sklepu natychmiast po zmianie statusu transakcji.

Taki komunikat jest najczęściej przekazywany za pomocą webhooka.

Webhook może poinformować zewnętrzny system również o:

• utworzeniu zamówienia,
• zmianie jego statusu,
• wykonaniu zwrotu,
• utworzeniu przesyłki,
• doręczeniu paczki,
• wysłaniu formularza,
• rejestracji użytkownika,
• zmianie danych produktu,
• anulowaniu subskrypcji,
• zakończeniu zadania w systemie.

Webhook pozwala systemom reagować na zdarzenia bez ciągłego pytania, czy pojawiło się coś nowego.

Nie oznacza to jednak, że wystarczy przygotować adres odbiorczy i przyjąć dowolne dane. Webhook może zostać wysłany kilka razy, dotrzeć z opóźnieniem, przyjść w innej kolejności albo zostać sfałszowany przez osobę nieuprawnioną.

Jeżeli odbiorca nie potrafi rozpoznać duplikatu, jedno opłacone zamówienie może zostać przetworzone dwukrotnie. Jeżeli nie sprawdza podpisu, ktoś może próbować samodzielnie wysłać fałszywe potwierdzenie płatności.

W swojej pracy regularnie spotykam integracje, w których webhook jest traktowany jak zwykły formularz kontaktowy. System odbiera dane, wykonuje od razu kilkanaście operacji i zwraca odpowiedź dopiero po zakończeniu całego procesu.

Gdy zewnętrzna usługa nie otrzymuje odpowiedzi wystarczająco szybko, uznaje próbę za nieudaną i wysyła webhook ponownie. Integracja tworzy wtedy drugi dokument, ponownie zmienia stan albo wysyła klientowi kolejną wiadomość.

Poprawna obsługa webhooków wymaga więc więcej niż samego odbioru danych. Potrzebne są zabezpieczenia, kolejka, logowanie, kontrola duplikatów, przemyślana obsługa błędów i jasne określenie, który system jest źródłem prawdy.

Co to jest webhook?

Webhook jest automatycznym komunikatem wysyłanym przez jeden system do drugiego po wystąpieniu określonego zdarzenia.

System wysyłający może poinformować na przykład:

• płatność została zakończona,
• zamówienie zostało utworzone,
• produkt zmienił stan,
• przesyłka została doręczona,
• użytkownik anulował subskrypcję,
• formularz został prawidłowo wysłany.

Webhook jest zwykle żądaniem HTTP wysyłanym pod wcześniej skonfigurowany adres odbiorcy.

Żądanie może zawierać:

• nazwę zdarzenia,
• unikalny identyfikator komunikatu,
• datę i czas,
• dane obiektu,
• status,
• podpis bezpieczeństwa,
• wersję formatu.

Odbiorca analizuje komunikat i wykonuje odpowiednie działanie.

Prosty przykład działania webhooka

Klient płaci za zamówienie w zewnętrznym systemie.

Proces może wyglądać następująco:

1. Sklep tworzy transakcję u operatora płatności.
2. Klient wykonuje płatność.
3. Operator zmienia status transakcji na opłaconą.
4. Operator wysyła webhook do sklepu.
5. Sklep sprawdza autentyczność komunikatu.
6. Sklep rozpoznaje transakcję i porównuje jej dane.
7. Zamówienie otrzymuje odpowiedni status.
8. System rozpoczyna dalszą realizację.

Webhook nie musi zawierać wszystkich szczegółów. Może przekazać wyłącznie identyfikator zdarzenia lub transakcji.

Odbiorca może wtedy użyć API operatora i samodzielnie pobrać aktualne dane z zaufanego źródła.

Czym webhook różni się od API?

Webhook i API są mechanizmami komunikacji pomiędzy systemami, ale pełnią inne role.

W klasycznym użyciu API jeden system inicjuje zapytanie:

Podaj mi aktualny status płatności.

W webhooku system źródłowy sam wysyła informację:

Status płatności właśnie się zmienił.

Najprostszy podział wygląda następująco:

• API służy do aktywnego pobierania danych lub wykonywania operacji.
• Webhook służy do informowania o wystąpieniu zdarzenia.

Oba rozwiązania bardzo często współpracują.

Webhook informuje, że płatność zmieniła status, a API pozwala pobrać pełne szczegóły transakcji.

Webhook a polling

Polling polega na regularnym odpytywaniu systemu o nowe dane.

Sklep może na przykład co pięć minut wysyłać pytanie:

Czy status transakcji numer 123 uległ zmianie?

Jeżeli zmiany występują rzadko, większość żądań nie przynosi nowych informacji.

Webhook odwraca ten model. System wysyła komunikat tylko wtedy, gdy faktycznie wydarzyło się coś istotnego.

Zalety webhooka względem pollingu

• szybsza reakcja na zdarzenie,
• mniejsza liczba pustych zapytań,
• mniejsze obciążenie API,
• ograniczenie zużycia limitów,
• prostsze uruchamianie automatyzacji.

Zalety pollingu

• odbiorca sam kontroluje moment pobrania danych,
• można łatwiej odbudować brakujące informacje,
• proces nie zależy wyłącznie od dostarczenia komunikatu,
• może działać z systemem, który nie obsługuje webhooków.

Najbardziej niezawodne integracje często łączą oba mechanizmy.

Webhook zapewnia szybką reakcję, a okresowa synchronizacja kontrolna wykrywa zdarzenia, które nie dotarły albo nie zostały przetworzone.

Kto jest nadawcą, a kto odbiorcą webhooka?

Nadawca to system, w którym wystąpiło zdarzenie.

Odbiorca to system posiadający adres, pod który nadawca wysyła komunikat.

Przykłady:

• operator płatności jest nadawcą, a sklep odbiorcą,
• WooCommerce jest nadawcą, a ERP odbiorcą,
• system kurierski jest nadawcą, a CRM odbiorcą,
• formularz jest nadawcą, a platforma automatyzacji odbiorcą.

Jeden system może być jednocześnie nadawcą i odbiorcą różnych webhooków.

Sklep może odbierać statusy płatności, a równocześnie wysyłać do ERP informację o nowym zamówieniu.

Czym jest endpoint webhooka?

Endpoint webhooka jest adresem, pod który zewnętrzny system wysyła komunikaty.

Powinien:

• korzystać z HTTPS,
• być dostępny z internetu,
• obsługiwać odpowiednią metodę HTTP,
• przyjmować wymagany format danych,
• sprawdzać autentyczność nadawcy,
• szybko zwracać odpowiedź,
• zapisywać wynik przetwarzania.

Endpoint nie powinien być zwykłą stroną WordPressa wymagającą sesji administratora albo zalogowania użytkownika.

Powinien być osobnym, kontrolowanym punktem integracji.

Jak webhook przekazuje dane?

Najczęściej webhook wysyłany jest metodą POST.

Dane mogą znajdować się w:

• treści żądania,
• nagłówkach,
• parametrach adresu,
• kombinacji kilku elementów.

Popularne formaty to:

• JSON,
• XML,
• dane formularza,
• zwykły tekst.

Format musi być dokładnie opisany w dokumentacji nadawcy.

Odbiorca nie powinien zakładać, że każde pole zawsze wystąpi. Niektóre wartości mogą być opcjonalne, puste albo zależne od rodzaju zdarzenia.

Co może zawierać webhook?

Przykładowy komunikat może zawierać:

• identyfikator zdarzenia,
• typ zdarzenia,
• datę utworzenia,
• identyfikator obiektu,
• nowy status,
• poprzedni status,
• kwotę,
• walutę,
• dane techniczne,
• podpis.

Webhook płatniczy może informować o:

• identyfikatorze transakcji,
• numerze zamówienia,
• kwocie,
• walucie,
• statusie,
• czasie zmiany.

Webhook sklepu może zawierać dane całego zamówienia albo tylko jego numer i rodzaj zmiany.

Webhook cienki i webhook pełny

Można spotkać dwa ogólne modele komunikatów.

Webhook cienki

Zawiera tylko podstawową informację o zdarzeniu, na przykład:

• typ zdarzenia,
• ID obiektu,
• ID komunikatu.

Odbiorca musi później użyć API, aby pobrać pełne i aktualne dane.

Zaletami są:

• mniejsza ilość przesyłanych informacji,
• pobieranie aktualnego stanu z systemu źródłowego,
• ograniczenie danych w komunikacie.

Webhook pełny

Zawiera komplet informacji potrzebnych do przetworzenia zdarzenia.

Może ograniczyć liczbę dodatkowych zapytań do API, ale wymaga szczególnie dokładnego sprawdzenia podpisu i wersji formatu.

Odbiorca musi również rozumieć, czy dane opisują stan aktualny, czy tylko stan z momentu utworzenia webhooka.

Dlaczego webhook może dotrzeć kilka razy?

System wysyłający zwykle oczekuje od odbiorcy odpowiedzi potwierdzającej przyjęcie komunikatu.

Jeżeli odpowiedź:

• nie nadejdzie,
• nadejdzie zbyt późno,
• zawiera kod błędu,
• połączenie zostanie przerwane,

nadawca może ponowić wysłanie webhooka.

Nawet jeśli odbiorca prawidłowo wykonał operację, odpowiedź mogła nie dotrzeć do nadawcy.

Oznacza to, że komunikat może zostać wysłany drugi raz mimo wcześniejszego sukcesu.

Duplikaty nie są wyjątkowym błędem. Są normalnym elementem pracy z webhookami i trzeba je obsłużyć już na etapie projektu.

Czym jest idempotencja webhooka?

Idempotencja oznacza, że ponowne przetworzenie tego samego zdarzenia nie tworzy kolejnego identycznego efektu.

Jeżeli webhook o opłaceniu zamówienia zostanie wysłany trzy razy, system powinien:

• rozpoznać, że dotyczy tego samego zdarzenia,
• nie utworzyć trzech płatności,
• nie wysłać trzech faktur,
• nie zmniejszyć stanu magazynowego trzykrotnie,
• nie wysłać klientowi kilku identycznych wiadomości.

Odbiorca może zapisywać unikalny identyfikator każdego przetworzonego zdarzenia.

Przed wykonaniem operacji sprawdza, czy ten identyfikator został już obsłużony.

Jak rozpoznawać duplikaty webhooków?

Najlepszym rozwiązaniem jest użycie unikalnego identyfikatora zdarzenia przekazanego przez nadawcę.

Można zapisywać:

• ID webhooka,
• ID zdarzenia,
• ID transakcji wraz z typem zdarzenia,
• unikalny klucz operacji.

Nie należy opierać się wyłącznie na czasie otrzymania komunikatu.

Dwa prawidłowe zdarzenia mogą nadejść w tej samej sekundzie, a ten sam webhook może zostać ponowiony po kilku godzinach.

Jeżeli nadawca nie udostępnia unikalnego ID, trzeba stworzyć kontrolowany klucz na podstawie dostępnych danych, ale rozwiązanie jest wtedy bardziej podatne na błędy.

Czy webhooki zawsze przychodzą w odpowiedniej kolejności?

Nie.

Sieć, kolejki nadawcy, ponowienia i różnice w czasie przetwarzania mogą zmienić kolejność dostarczenia.

Przykładowo system może odebrać:

1. informację o wysłaniu paczki,
2. a dopiero później opóźniony webhook o przygotowaniu zamówienia.

Jeżeli odbiorca bezwarunkowo zastosuje drugi komunikat, może cofnąć status przesyłki.

Dlatego warto uwzględniać:

• czas zdarzenia,
• numer wersji obiektu,
• dozwolone przejścia statusów,
• aktualny stan w systemie źródłowym.

Zdarzenie a aktualny stan obiektu

Webhook informuje, że określone zdarzenie wystąpiło. Nie zawsze oznacza, że zawiera aktualny stan obiektu w momencie odbioru.

Jeżeli webhook został wysłany z opóźnieniem, dane mogą być już nieaktualne.

Przykładowo:

1. płatność została zaakceptowana,
2. chwilę później została zwrócona,
3. webhook o akceptacji dotarł z opóźnieniem po webhooku o zwrocie.

W procesach krytycznych warto po otrzymaniu webhooka pobrać aktualny stan przez API.

Webhook staje się wtedy sygnałem:

Sprawdź ten obiekt, ponieważ coś się zmieniło.

Jaką odpowiedź powinien zwrócić odbiorca?

Po prawidłowym przyjęciu webhooka odbiorca powinien zwrócić kod sukcesu z grupy 2xx.

Dokładny kod zależy od wymagań nadawcy i sposobu obsługi.

Najważniejsze jest rozróżnienie:

• komunikat został prawidłowo odebrany,
• komunikat jest nieprawidłowy,
• wystąpił chwilowy błąd serwera,
• zdarzenie nie może zostać przetworzone.

Nie należy zawsze zwracać sukcesu niezależnie od wyniku, ponieważ nadawca uzna wtedy wadliwe zdarzenie za dostarczone i może go więcej nie ponowić.

Nie należy również zwracać błędu po prawidłowym zapisaniu webhooka tylko dlatego, że późniejsza operacja w innym systemie chwilowo się nie udała.

Dlaczego webhook powinien odpowiadać szybko?

Nadawcy zwykle posiadają limit czasu oczekiwania na odpowiedź.

Jeżeli endpoint:

• generuje dokument,
• łączy się z ERP,
• tworzy przesyłkę,
• wysyła kilka wiadomości,
• przelicza stany całego katalogu,

odpowiedź może nadejść zbyt późno.

Nadawca uzna próbę za nieudaną i zaplanuje ponowienie.

Lepszy proces wygląda tak:

1. Odbiorca sprawdza podstawową poprawność i podpis.
2. Zapisuje webhook w bazie lub kolejce.
3. Zwraca szybką odpowiedź sukcesu.
4. Dalsze operacje wykonuje w tle.

Webhook i kolejka zadań

Kolejka oddziela przyjęcie komunikatu od wykonania długotrwałego procesu.

Po odebraniu webhooka system może utworzyć zadanie:

• zaktualizuj zamówienie,
• pobierz transakcję z API,
• wyślij dane do ERP,
• utwórz fakturę,
• powiadom klienta.

Kolejka umożliwia:

• szybką odpowiedź nadawcy,
• kontrolowane ponawianie operacji,
• ograniczanie liczby równoległych zadań,
• przetwarzanie po awarii zewnętrznego systemu,
• monitorowanie nieudanych zadań.

W WordPressie można wykorzystać harmonogram zadań, własną kolejkę albo system przetwarzania działający poza zwykłym żądaniem użytkownika.

Czy zapisanie webhooka oznacza jego przetworzenie?

Nie.

Warto rozróżniać statusy takie jak:

• odebrany,
• zweryfikowany,
• oczekujący,
• przetwarzany,
• zakończony,
• nieudany,
• odrzucony,
• duplikat.

Dzięki temu administrator wie, czy komunikat dotarł, ale utknął podczas dalszej operacji.

Samo zwrócenie nadawcy kodu sukcesu nie potwierdza, że wszystkie dalsze działania zostały już wykonane.

Jak działa ponawianie webhooków?

Każdy dostawca może posiadać własną politykę ponowień.

Webhook może być wysyłany:

• kilka razy w krótkich odstępach,
• z rosnącym opóźnieniem,
• przez kilka godzin,
• przez kilka dni,
• do momentu ręcznego wyłączenia.

Dokumentacja powinna określać:

• które odpowiedzi powodują ponowienie,
• jak długo trwają próby,
• czy zachowywany jest ten sam identyfikator zdarzenia,
• czy istnieje możliwość ręcznego ponownego wysłania.

Odbiorca nie powinien zakładać, że webhook zostanie wysłany tylko raz.

Czym jest martwa kolejka?

Jeżeli zadanie nie może zostać zakończone mimo kolejnych prób, powinno trafić do osobnego miejsca przeznaczonego dla nieudanych komunikatów.

Taka kolejka może zawierać zdarzenia, których nie udało się przetworzyć z powodu:

• braku produktu,
• nieprawidłowego mapowania,
• trwale odrzuconego żądania,
• błędu danych,
• braku uprawnień,
• nieobsługiwanej wersji.

Administrator powinien móc:

• zobaczyć przyczynę,
• poprawić dane,
• ponowić zdarzenie,
• oznaczyć je jako rozwiązane,
• odrzucić je świadomie.

Jak zabezpieczyć webhook?

Sam fakt, że żądanie trafiło pod trudno odgadniony adres, nie potwierdza jego autentyczności.

Webhook powinien korzystać z kilku warstw ochrony.

Najważniejsze mechanizmy to:

• HTTPS,
• podpis kryptograficzny,
• sekret współdzielony,
• kontrola czasu komunikatu,
• ochrona przed ponownym użyciem,
• walidacja formatu,
• ograniczenie uprawnień,
• logowanie prób.

Dlaczego HTTPS jest konieczne?

HTTPS szyfruje komunikację pomiędzy nadawcą i odbiorcą.

Pomaga chronić przed:

• odczytaniem danych podczas transmisji,
• modyfikacją komunikatu po drodze,
• podszywaniem się pod endpoint.

Certyfikat powinien być ważny i prawidłowo skonfigurowany.

Webhook wysyłany do nieprawidłowego certyfikatu może być odrzucany przez system nadawcy.

Czym jest podpis webhooka?

Podpis pozwala sprawdzić, czy komunikat został utworzony przez znanego nadawcę i nie został zmieniony.

Nadawca tworzy podpis na podstawie:

• treści żądania,
• sekretu znanego obu stronom,
• czasem znacznika czasu lub dodatkowych danych.

Odbiorca wykonuje to samo obliczenie i porównuje wynik z podpisem przesłanym w nagłówku.

Jeżeli wartości się różnią, komunikat powinien zostać odrzucony.

Dlaczego trzeba weryfikować surową treść żądania?

Wiele mechanizmów podpisu obliczanych jest na podstawie dokładnych bajtów przesłanego komunikatu.

Jeżeli odbiorca najpierw przetworzy JSON, zmieni kolejność pól albo format znaków, ponownie utworzony tekst może różnić się od oryginału.

Podpis należy więc często sprawdzać na surowej treści żądania przed jej dalszym przekształceniem.

Dokładna procedura musi odpowiadać dokumentacji nadawcy.

Znacznik czasu i ochrona przed powtórzeniem

Poprawnie podpisany webhook może zostać przechwycony i ponownie wysłany później.

Aby ograniczyć takie ryzyko, nadawca może umieścić w podpisie znacznik czasu.

Odbiorca sprawdza:

• czy podpis jest prawidłowy,
• czy komunikat nie jest zbyt stary,
• czy jego identyfikator nie został już wykorzystany.

Trzeba uwzględnić niewielką różnicę czasu pomiędzy serwerami, ale nie akceptować dowolnie starych komunikatów.

Czy można zabezpieczyć webhook tokenem w adresie?

Sekretny fragment adresu może ograniczyć przypadkowe żądania, ale nie powinien być jedynym zabezpieczeniem.

Adres może trafić do:

• logów serwera,
• historii konfiguracji,
• systemu monitoringu,
• dokumentacji,
• panelu zewnętrznej usługi.

Lepszym rozwiązaniem jest podpis komunikatu albo właściwe uwierzytelnianie w nagłówkach.

Ograniczenie po adresach IP

Niektórzy nadawcy publikują listę adresów IP, z których wysyłają webhooki.

Filtrowanie może stanowić dodatkową warstwę ochrony, ale ma ograniczenia:

• adresy mogą się zmieniać,
• usługa może korzystać z wielu regionów,
• lista może być niepełna,
• proxy i infrastruktura chmurowa mogą komplikować identyfikację.

Nie zastępuje to weryfikacji podpisu.

Walidacja danych webhooka

Nawet prawidłowo podpisane dane muszą zostać sprawdzone.

Webhook może zawierać:

• brakujące pola,
• nieobsługiwaną wartość,
• nowy typ statusu,
• kwotę w innej walucie,
• identyfikator nieistniejącego obiektu.

Odbiorca powinien sprawdzać:

• typ zdarzenia,
• format ID,
• kwotę,
• walutę,
• status,
• obecność wymaganych pól,
• zgodność z istniejącym rekordem.

Nie należy bezpośrednio zapisywać wszystkich wartości tylko dlatego, że nadawca został rozpoznany.

Webhook płatniczy

Webhook operatora płatności jest jednym z najbardziej krytycznych komunikatów w sklepie.

Może informować o:

• utworzeniu transakcji,
• oczekiwaniu na płatność,
• zaakceptowaniu płatności,
• odrzuceniu,
• anulowaniu,
• zwrocie,
• częściowym zwrocie,
• sporze lub cofnięciu środków.

Sklep powinien porównać dane webhooka z własnym zamówieniem.

Trzeba sprawdzić między innymi:

• czy numer zamówienia istnieje,
• czy identyfikator transakcji jest zgodny,
• czy kwota się zgadza,
• czy waluta jest prawidłowa,
• czy nowy status jest dozwolony,
• czy zdarzenie nie zostało już obsłużone.

Dlaczego powrót klienta z płatności nie wystarcza?

Po zakończeniu płatności klient może zostać przekierowany do sklepu.

Nie można jednak uznawać zamówienia za opłacone wyłącznie na podstawie wejścia na stronę powrotu.

Użytkownik może:

• zamknąć okno przed powrotem,
• stracić połączenie,
• otworzyć adres ręcznie,
• wrócić mimo nieudanej płatności,
• odświeżyć stronę.

Wiarygodne potwierdzenie powinno pochodzić z webhooka operatora lub z weryfikacji statusu przez API.

Webhook zamówienia

Sklep może wysłać webhook po:

• utworzeniu zamówienia,
• zmianie statusu,
• aktualizacji danych,
• dodaniu notatki,
• anulowaniu,
• wykonaniu zwrotu.

Odbiorcą może być:

• ERP,
• system magazynowy,
• CRM,
• platforma automatyzacji,
• system wysyłkowy,
• hurtownia danych.

Trzeba określić, czy webhook ma zawierać pełne dane zamówienia, czy tylko uruchamiać pobranie przez API.

Webhook produktu

Webhook może informować o:

• utworzeniu produktu,
• zmianie ceny,
• zmianie stanu,
• aktualizacji opisu,
• usunięciu,
• zmianie wariantu.

Przy częstych aktualizacjach trzeba uważać na liczbę komunikatów.

Masowy import dziesięciu tysięcy produktów może wygenerować dziesiątki tysięcy webhooków i przeciążyć odbiorcę.

W takich sytuacjach przydatne są:

• kolejki,
• operacje zbiorcze,
• ograniczenie zdarzeń,
• synchronizacja przyrostowa,
• okresowe pobieranie zmian przez API.

Webhook kurierski

System przewoźnika może wysyłać informacje o:

• utworzeniu przesyłki,
• odebraniu paczki,
• sortowaniu,
• wydaniu do doręczenia,
• doręczeniu,
• problemie z dostawą,
• zwrocie do nadawcy.

Sklep może na tej podstawie:

• aktualizować zamówienie,
• wysyłać wiadomość klientowi,
• uruchamiać automatyzację posprzedażową,
• wykrywać niedoręczone paczki.

Nie każdy status przewoźnika powinien być bezpośrednio mapowany na status WooCommerce. System kurierski może posiadać znacznie bardziej szczegółowy proces.

Webhook formularza

Po prawidłowym wysłaniu formularza webhook może przekazać dane do:

• CRM,
• systemu rezerwacji,
• narzędzia automatyzującego,
• systemu obsługi zgłoszeń,
• platformy marketingowej.

Webhook powinien być uruchamiany po prawidłowym przyjęciu formularza, a nie po samym kliknięciu przycisku.

Trzeba również kontrolować:

• spam,
• duplikaty,
• zgody użytkownika,
• zakres przekazywanych danych,
• błędy systemu docelowego.

Webhook w WordPressie

WordPress może zarówno wysyłać, jak i odbierać webhooki.

Własna wtyczka może:

• utworzyć endpoint REST API,
• sprawdzić podpis,
• zapisać zdarzenie,
• dodać zadanie do kolejki,
• zwrócić odpowiedź,
• wykonać dalszą operację w tle.

WordPress może również wysłać webhook po wystąpieniu określonego działania, wykorzystując:

• hooki systemowe,
• zdarzenia wtyczek,
• REST API,
• własny kod integracyjny.

Webhook w WooCommerce

WooCommerce posiada mechanizmy webhooków pozwalające informować zewnętrzne systemy o wybranych zmianach.

Mogą dotyczyć między innymi:

• zamówień,
• produktów,
• klientów,
• kuponów,
• niestandardowych działań.

Konfiguracja powinna określać:

• temat webhooka,
• adres dostawy,
• sekret,
• status aktywności,
• wersję API.

Sam panel WooCommerce nie zastępuje analizy procesu. Trzeba sprawdzić, czy wybrane zdarzenie uruchamia się dokładnie w potrzebnym momencie.

Czy webhook WooCommerce wystarczy do każdej integracji?

Nie zawsze.

Standardowy webhook może wysłać zbyt dużo albo zbyt mało danych.

Może również nie obsługiwać:

• niestandardowego statusu,
• dedykowanych pól,
• konkretnego etapu procesu,
• nietypowego mapowania,
• potwierdzenia wykonania operacji w systemie docelowym.

Własna integracja może wymagać:

• niestandardowego zdarzenia,
• przekształcenia danych,
• kolejki,
• kontroli odpowiedzi,
• ponawiania,
• zapisu identyfikatorów systemu docelowego.

Webhook a Action Scheduler

W ekosystemie WooCommerce często wykorzystuje się system zadań działających w tle.

Może on pomóc:

• odłożyć przetwarzanie webhooka,
• ponowić nieudaną integrację,
• kontrolować kolejkę,
• przeglądać historię zadań,
• ograniczyć blokowanie żądania klienta.

Trzeba jednak monitorować kolejkę.

Zadania mogą pozostawać oczekujące z powodu:

• niedziałającego harmonogramu,
• błędu PHP,
• braku zasobów,
• blokady zewnętrznego API,
• ciągłego ponawiania wadliwych danych.

Webhook a WordPress Cron

WordPress Cron może uruchamiać zadania w tle, ale nie jest klasycznym stałym procesem systemowym.

W typowej konfiguracji jego wykonanie zależy od ruchu na stronie.

Przy małym ruchu zadanie może uruchomić się później. Przy dużej liczbie zadań standardowy mechanizm może być niewystarczający.

W krytycznych integracjach warto rozważyć:

• prawdziwy cron serwera,
• dedykowaną kolejkę,
• proces pracujący w tle,
• zewnętrzny system kolejkowy.

Webhook w narzędziach automatyzujących

Platformy no-code i low-code często udostępniają własne adresy webhooków.

Proces może wyglądać następująco:

1. Formularz wysyła webhook.
2. Platforma odbiera dane.
3. Tworzy kontakt w CRM.
4. Dodaje rekord do arkusza.
5. Wysyła powiadomienie.

Takie rozwiązanie pozwala szybko budować automatyzacje, ale trzeba sprawdzić:

• gdzie przetwarzane są dane,
• jak są zabezpieczone,
• czy platforma obsługuje podpisy,
• jak działa ponawianie,
• czy wykrywa duplikaty,
• jakie posiada limity,
• co stanie się po wyczerpaniu abonamentu.

Webhook a dane osobowe

Webhook może przekazywać dane klientów, pracowników lub użytkowników.

Trzeba określić:

• które dane są rzeczywiście potrzebne,
• w jakim celu są przesyłane,
• kto jest odbiorcą,
• gdzie znajduje się infrastruktura,
• jak długo przechowywane są logi,
• kto posiada dostęp.

Nie należy wysyłać pełnego zamówienia, jeżeli odbiorca potrzebuje wyłącznie numeru i statusu.

Minimalizacja danych zmniejsza ryzyko i ułatwia kontrolę integracji.

Logowanie webhooków

Każdy istotny webhook powinien pozostawić ślad umożliwiający diagnostykę.

Log może zawierać:

• czas odbioru,
• identyfikator zdarzenia,
• typ webhooka,
• wynik weryfikacji podpisu,
• status przetwarzania,
• liczbę prób,
• powiązany obiekt,
• kod błędu.

Nie należy bez potrzeby zapisywać:

• pełnych sekretów,
• tokenów,
• danych kart,
• haseł,
• nadmiarowych danych osobowych.

Log powinien być chroniony i posiadać ustalony czas przechowywania.

Co powinien pokazywać panel webhooków?

Przy większej integracji warto przygotować panel pokazujący:

• ostatnio odebrane zdarzenia,
• ich status,
• rodzaj,
• powiązany rekord,
• liczbę prób,
• czas przetwarzania,
• treść błędu,
• możliwość ponowienia.

Administrator nie powinien potrzebować dostępu do surowych logów serwera, aby sprawdzić, dlaczego jedno zamówienie nie trafiło do ERP.

Monitoring webhooków

Integracja może przestać odbierać webhooki z powodu:

• wygaśnięcia certyfikatu,
• zmiany adresu,
• blokady firewalla,
• błędu aplikacji,
• pełnej kolejki,
• braku miejsca na dysku,
• zmiany podpisu lub wersji API.

Monitoring powinien kontrolować:

• czas ostatniego zdarzenia,
• liczbę webhooków,
• liczbę błędów,
• czas odpowiedzi,
• rozmiar kolejki,
• liczbę ponowień,
• nietypowy spadek lub wzrost ruchu.

Brak webhooków może być równie istotnym sygnałem jak duża liczba błędów.

Alerty i powiadomienia

Administrator powinien otrzymać alert, gdy:

• kolejka przestaje się opróżniać,
• wzrasta liczba odrzuconych podpisów,
• system docelowy jest niedostępny,
• ważne zdarzenie nie zostało przetworzone,
• webhook nie pojawił się przez nietypowo długi czas,
• liczba ponowień przekracza ustalony próg.

Alert powinien zawierać informacje potrzebne do reakcji, a nie jedynie ogólny komunikat o błędzie.

Jak testować webhook?

Test nie powinien ograniczać się do jednego prawidłowego komunikatu.

Sprawdzam:

• poprawny webhook,
• błędny podpis,
• brak podpisu,
• stary znacznik czasu,
• powtórzenie tego samego zdarzenia,
• brak wymaganego pola,
• nieznany typ zdarzenia,
• nieistniejący obiekt,
• niedostępność systemu docelowego,
• opóźnione dostarczenie,
• zmienioną kolejność zdarzeń.

Testuję również zachowanie po ponowieniu.

Jedno zdarzenie wysłane kilka razy nie powinno tworzyć kilku identycznych efektów.

Narzędzia do testowania webhooków

Podczas wdrożenia można wykorzystać tymczasowy adres odbierający żądania i pokazujący ich zawartość.

Pozwala to sprawdzić:

• nagłówki,
• format treści,
• typ zdarzenia,
• podpis,
• częstotliwość wysyłki,
• zachowanie ponowień.

Tymczasowy odbiornik nie powinien być używany do rzeczywistych danych klientów bez odpowiedniej kontroli bezpieczeństwa.

Po zakończeniu testów adres należy usunąć z konfiguracji produkcyjnej.

Środowisko testowe i produkcyjne

Dane testowe nie powinny trafiać do produkcyjnych systemów.

Warto posiadać osobne:

• endpointy,
• sekrety,
• identyfikatory kont,
• kolejki,
• logi,
• dane testowe.

Webhook ze środowiska testowego nie powinien zmieniać prawdziwego zamówienia klienta.

Po przejściu testów nadal wykonuję kontrolowany test produkcyjny, ponieważ środowisko testowe może różnić się zachowaniem od rzeczywistego systemu.

Jak odtworzyć webhook?

Dostawca może umożliwiać ręczne ponowne wysłanie wcześniejszego zdarzenia.

Jeżeli nie posiada takiej funkcji, własny system może przechowywać bezpieczną kopię komunikatu umożliwiającą ponowne przetworzenie.

Trzeba odróżnić:

• ponowne wysłanie komunikatu,
• ponowne wykonanie procesu biznesowego.

Idempotencja powinna zabezpieczyć system przed utworzeniem duplikatu również podczas ręcznego odtwarzania.

Wersjonowanie webhooków

Format komunikatu może zmieniać się wraz z rozwojem systemu.

Nowa wersja może:

• dodać pola,
• usunąć stare pola,
• zmienić typ wartości,
• zmienić nazwę zdarzenia,
• wprowadzić nowy sposób podpisu.

Webhook może wskazywać wersję w:

• adresie endpointu,
• nagłówku,
• treści zdarzenia,
• konfiguracji subskrypcji.

Odbiorca powinien wiedzieć, jakie wersje obsługuje i jak zareagować na nieznaną wersję.

Czy dodatkowe pole może zepsuć integrację?

Dobrze napisany odbiorca powinien ignorować nieznane pola, jeżeli nie wpływają one na wymagany proces.

Integracja nie powinna przestać działać tylko dlatego, że nadawca dodał nową opcjonalną informację.

Bardziej niebezpieczne są zmiany takie jak:

• usunięcie wymaganego pola,
• zmiana typu liczby na tekst,
• zmiana znaczenia statusu,
• zmiana sposobu podpisywania.

Takie modyfikacje wymagają wersjonowania i odpowiedniego okresu migracji.

Webhook a awaria systemu docelowego

Odbiorca może prawidłowo przyjąć webhook, ale nie być w stanie wykonać dalszej operacji, ponieważ ERP, CRM albo system kurierski nie działa.

Nie powinien wtedy tracić zdarzenia.

Proces powinien:

• zapisać komunikat,
• utworzyć zadanie,
• ponawiać operację,
• zwiększać odstęp pomiędzy próbami,
• powiadomić administratora po przekroczeniu limitu.

Użytkownik nie powinien być zmuszony do ponownego składania zamówienia tylko dlatego, że zewnętrzny system był chwilowo niedostępny.

Webhook a transakcje bazodanowe

Przetworzenie webhooka może wymagać kilku zmian w bazie.

Jeżeli część zostanie wykonana, a część zakończy się błędem, dane mogą pozostać niespójne.

W krytycznych operacjach warto:

• wykorzystać transakcję bazodanową, jeżeli środowisko na to pozwala,
• zapisywać etapy procesu,
• projektować operacje możliwe do bezpiecznego ponowienia,
• nie oznaczać zadania jako zakończone przed pełnym sukcesem.

Webhook a blokady równoległego przetwarzania

Dwa webhooki dotyczące tego samego zamówienia mogą być przetwarzane jednocześnie.

Może to prowadzić do konfliktów:

• oba procesy odczytują stary status,
• każdy zapisuje inną wartość,
• jeden nadpisuje efekt drugiego,
• powstają podwójne dokumenty.

Rozwiązaniem może być:

• blokada dla konkretnego obiektu,
• kolejka zachowująca kolejność,
• kontrola wersji rekordu,
• atomowa aktualizacja,
• ponowna weryfikacja stanu przed zapisem.

Czym jest wyścig procesów?

Wyścig występuje, gdy wynik zależy od kolejności równoległych operacji.

Przykładowo:

1. Webhook płatności próbuje zmienić zamówienie na opłacone.
2. Webhook anulowania próbuje zmienić je na anulowane.
3. Oba procesy rozpoczynają się prawie równocześnie.

Bez odpowiednich reguł ostateczny status może zależeć od tego, który zapis zakończył się jako ostatni.

Proces powinien uwzględniać dozwolone przejścia i aktualny stan źródłowy.

Webhook a cache

Po zmianie produktu lub zamówienia trzeba czasem unieważnić cache.

Jeżeli webhook aktualizuje cenę, a strona nadal pokazuje poprzednią wartość z cache, użytkownik otrzymuje nieaktualne dane.

Nie należy jednak czyścić całego cache strony po każdej drobnej zmianie jednego produktu.

Lepsze jest selektywne unieważnienie:

• konkretnego produktu,
• jego kategorii,
• powiązanych fragmentów,
• cache zewnętrznego API.

Webhook a wydajność strony

Duża liczba webhooków może obciążyć sklep, jeżeli każdy komunikat uruchamia kosztowny proces synchroniczny.

Problemy mogą wystąpić podczas:

• masowej zmiany produktów,
• dużego importu,
• promocji generującej wiele płatności,
• awarii powodującej lawinę ponowień,
• ataku na publiczny endpoint.

Pomagają:

• kolejki,
• limity przetwarzania,
• kontrola rozmiaru żądania,
• ochrona przed nadużyciem,
• skalowanie pracowników kolejki,
• grupowanie zdarzeń.

Czy webhook gwarantuje dostarczenie?

Webhook działa przez sieć, dlatego nie daje absolutnej gwarancji, że komunikat zawsze dotrze i zostanie przetworzony.

Niezawodność zwiększają:

• ponowienia nadawcy,
• szybkie potwierdzenie odbioru,
• kolejka odbiorcy,
• idempotencja,
• logi,
• monitoring,
• okresowa synchronizacja kontrolna.

W procesach krytycznych webhook nie powinien być jedynym mechanizmem kontroli zgodności systemów.

Webhook i proces uzgadniania danych

Okresowe uzgadnianie porównuje dane w dwóch systemach.

Może sprawdzać:

• czy wszystkie opłacone transakcje posiadają właściwy status zamówienia,
• czy wszystkie zamówienia trafiły do ERP,
• czy każda przesyłka ma zapisany numer,
• czy stan produktów jest zgodny.

Jeżeli różnica zostanie wykryta, system może:

• naprawić ją automatycznie,
• utworzyć zadanie,
• powiadomić administratora,
• ponownie pobrać dane przez API.

Najczęstsze błędy przy webhookach

Brak weryfikacji podpisu

Endpoint ufa każdemu żądaniu wysłanemu pod jego adres.

Sekret zapisany w publicznym kodzie

Dane zabezpieczające można odczytać w przeglądarce lub publicznym repozytorium.

Wykonywanie całego procesu przed odpowiedzią

Endpoint odpowiada zbyt wolno i nadawca ponawia komunikat.

Brak idempotencji

Każde ponowienie tworzy kolejny dokument lub zmienia stan.

Brak unikalnego identyfikatora zdarzenia

System nie potrafi rozpoznać duplikatu.

Założenie prawidłowej kolejności

Opóźniony webhook cofa obiekt do wcześniejszego statusu.

Brak kontroli kwoty i waluty

Zamówienie zostaje uznane za opłacone mimo niezgodności transakcji.

Zaufanie do samego powrotu z płatności

Sklep zmienia status bez wiarygodnego potwierdzenia operatora.

Zawsze zwracany sukces

Nieprawidłowe zdarzenia są bezpowrotnie odrzucane bez możliwości ponowienia.

Zawsze zwracany błąd przy problemie dalszego systemu

Nadawca ponawia webhook, mimo że został już bezpiecznie zapisany w kolejce.

Brak kolejki

Awaria ERP blokuje endpoint i powoduje lawinę ponowień.

Nieograniczone ponawianie

Trwale wadliwe zdarzenie jest przetwarzane bez końca.

Brak martwej kolejki

Nieudane zdarzenia znikają albo pozostają stale oczekujące.

Logowanie danych wrażliwych

Pełne payloady z danymi klientów są przechowywane bez kontroli.

Brak monitoringu

Endpoint nie działa przez kilka dni, ale nikt nie otrzymuje alertu.

Jeden endpoint dla testów i produkcji

Testowe zdarzenia modyfikują prawdziwe zamówienia.

Brak wersjonowania

Zmiana formatu komunikatu nagle przerywa integrację.

Brak dokumentacji mapowania

Po zmianie wykonawcy nikt nie wie, jak interpretowane są statusy i pola.

Jak samodzielnie ocenić webhook?

Podstawową kontrolę można rozpocząć od odpowiedzi na kilka pytań:

1. Jaki system wysyła webhook?
2. Jakie zdarzenie go uruchamia?
3. Pod jaki adres jest wysyłany?
4. Czy endpoint korzysta z HTTPS?
5. Jak weryfikowany jest podpis?
6. Gdzie przechowywany jest sekret?
7. Czy komunikat posiada unikalne ID?
8. Jak wykrywane są duplikaty?
9. Czy kolejność zdarzeń jest gwarantowana?
10. Czy po webhooku pobierany jest aktualny stan przez API?
11. Jak szybko endpoint zwraca odpowiedź?
12. Czy dalsza praca odbywa się w kolejce?
13. Jak działa ponawianie?
14. Co dzieje się po trwałym błędzie?
15. Czy istnieje panel lub log zdarzeń?
16. Czy administrator otrzymuje alert?
17. Czy testy i produkcja mają osobne sekrety?
18. Czy można ponownie przetworzyć zdarzenie?
19. Jak obsługiwana jest zmiana wersji?
20. Czy działa okresowe uzgadnianie danych?

Jak wygląda prawidłowy proces wdrożenia webhooka?

1. Określam zdarzenie – ustalam, co dokładnie ma uruchamiać komunikat.
2. Definiuję odpowiedzialność systemów – wskazuję źródło prawdy dla statusu i danych.
3. Analizuję dokumentację – sprawdzam format, podpis, odpowiedzi i politykę ponowień.
4. Projektuję endpoint – przygotowuję bezpieczny adres odbierający właściwą metodę.
5. Wdrażam weryfikację podpisu – sprawdzam surową treść, sekret i znacznik czasu.
6. Waliduję dane – kontroluję typ zdarzenia, identyfikatory, kwoty i wymagane pola.
7. Zapisuję komunikat – nadaję mu status i zachowuję dane potrzebne do diagnostyki.
8. Dodaję idempotencję – uniemożliwiam wielokrotne wykonanie tego samego efektu.
9. Zwracam szybką odpowiedź – nie blokuję nadawcy długim procesem.
10. Przekazuję zadanie do kolejki – dalsze operacje wykonuję w tle.
11. Obsługuję błędy – rozróżniam problem chwilowy, trwały i biznesowy.
12. Konfiguruję ponowienia – ustalam limity oraz rosnące odstępy.
13. Tworzę martwą kolejkę – oddzielam zdarzenia wymagające ręcznej interwencji.
14. Testuję duplikaty i kolejność – wysyłam te same zdarzenia wielokrotnie i w różnej kolejności.
15. Wdrażam monitoring – kontroluję endpoint, kolejkę, błędy i czas przetwarzania.
16. Dokumentuję rozwiązanie – zapisuję format, podpis, mapowanie i procedurę awaryjną.
17. Dodaję uzgadnianie danych – okresowo porównuję stan systemów.

Czy webhook zawsze jest najlepszym rozwiązaniem?

Nie.

Webhook sprawdza się szczególnie wtedy, gdy:

• reakcja powinna nastąpić szybko,
• zdarzenia występują nieregularnie,
• system źródłowy obsługuje ponowienia,
• odbiorca może udostępnić bezpieczny endpoint,
• proces można wykonać asynchronicznie.

Polling lub okresowy import może być lepszy, gdy:

• system nie obsługuje webhooków,
• dane zmieniają się rzadko,
• odbiorca nie może udostępnić publicznego endpointu,
• ważniejsze jest przetwarzanie zbiorcze,
• potrzebna jest pełna synchronizacja katalogu.

Najczęściej najlepszy rezultat daje połączenie mechanizmów: webhook uruchamia szybką reakcję, API dostarcza aktualne dane, a okresowa synchronizacja kontroluje kompletność.

Najważniejsze wnioski

• Webhook jest automatycznym komunikatem wysyłanym po wystąpieniu określonego zdarzenia.
• API jest zwykle aktywnie wywoływane przez klienta, a webhook jest inicjowany przez system źródłowy.
• Webhook ogranicza potrzebę ciągłego odpytywania API.
• Webhook i API często współpracują: komunikat informuje o zmianie, a API zwraca aktualne dane.
• Endpoint webhooka powinien korzystać z HTTPS i szybko odpowiadać.
• Dalsze operacje najlepiej wykonywać w kolejce poza głównym żądaniem.
• Webhook może zostać wysłany kilka razy i nie jest to sytuacja wyjątkowa.
• Idempotencja zapobiega wielokrotnemu wykonaniu tego samego efektu.
• Unikalny identyfikator zdarzenia pomaga rozpoznawać duplikaty.
• Webhooki nie zawsze docierają w kolejności utworzenia.
• Opóźniony komunikat może opisywać stan, który nie jest już aktualny.
• W krytycznych procesach warto pobrać aktualny stan obiektu przez API.
• Podpis kryptograficzny pozwala sprawdzić autentyczność i integralność komunikatu.
• Podpis należy często weryfikować na surowej treści żądania.
• Znacznik czasu i zapisane ID chronią przed ponownym wykorzystaniem starego webhooka.
• Adres z tajnym fragmentem nie powinien być jedynym zabezpieczeniem.
• Webhook płatniczy wymaga kontroli numeru zamówienia, kwoty, waluty, statusu i podpisu.
• Powrót klienta ze strony płatności nie jest wystarczającym potwierdzeniem transakcji.
• Kolejka pozwala obsługiwać chwilową niedostępność ERP, CRM i innych systemów.
• Trwale nieudane zdarzenia powinny trafiać do osobnej kolejki wymagającej interwencji.
• Logi muszą umożliwiać diagnostykę bez przechowywania nadmiarowych danych wrażliwych.
• Monitoring powinien kontrolować zarówno błędy, jak i brak oczekiwanych webhooków.
• Środowiska testowe i produkcyjne powinny posiadać osobne endpointy oraz sekrety.
• Format webhooka może się zmieniać, dlatego integracja wymaga wersjonowania i utrzymania.
• Webhook nie daje absolutnej gwarancji dostarczenia.
• Okresowe uzgadnianie danych pomaga wykrywać zdarzenia pominięte lub nieprzetworzone.
• Najlepsza integracja zaczyna się od procesu biznesowego, a nie od samego utworzenia publicznego adresu.

Nie wiesz, czy webhook w Twojej integracji działa niezawodnie?

Podczas analizy sprawdzam nie tylko to, czy system wysyła i odbiera komunikaty. Kontroluję podpisy, identyfikatory zdarzeń, ponowienia, kolejność, kolejki, mapowanie statusów, logi oraz zachowanie podczas awarii systemów zewnętrznych.

Mogę wskazać sytuacje, w których ten sam webhook tworzy kilka dokumentów, opóźnione zdarzenie cofa status zamówienia albo sklep uznaje płatność za zakończoną bez wiarygodnego potwierdzenia operatora.

Nie zakładam automatycznie, że trzeba przebudować całą integrację. Najpierw ustalam, czy problem znajduje się w konfiguracji nadawcy, bezpieczeństwie endpointu, obsłudze odpowiedzi, kolejce, idempotencji czy dalszym systemie. Dopiero później porządkuję proces i zabezpieczam go przed utratą oraz duplikacją danych.