Czym jest webhook w PrestaShop i kiedy ma sens

Definicja w jednym zdaniu: webhook w PrestaShop to mechanizm push — sklep sam wykonuje żądanie POST na wskazany przez Ciebie adres URL w momencie zajścia zdarzenia, zamiast czekania, aż Twój system co minutę zapyta o zmiany przez Webservice API.

To nie jest „lepsza wersja API”. To inne narzędzie i w części projektów po prostu się nie opłaca. W praktyce konkurują ze sobą trzy warianty.

Kryterium	Webhook	Webservice REST	Cron co 15 min
Kierunek	Push — sklep wysyła do Ciebie	Pull — Ty pytasz sklep	Pull — Ty pytasz sklep
Opóźnienie	Poniżej 1 s w trybie real-time	Zależne od interwału odpytywania	Do 15 minut
Koszt	Po stronie odbiorcy: endpoint, logi, obsługa błędów	Po stronie pytającego: limity, paginacja	Najniższy — jeden skrypt w cronie
Kontrola nad danymi	Tylko to, co wyśle sklep	Pełna: filtry, wybrane pola, zakres dat	Pełna, ale w stałych porcjach
Główne ryzyko	Brak natywnych ponowień i podpisu	Rate limit i paginacja (429, ucięte listy)	Opóźnienie dyskwalifikujące statusy płatności

Trzy scenariusze, w których webhook wygrywa:

• Zmiana statusu zamówienia do ERP/WMS — magazyn musi zacząć kompletację w kilka sekund od kliknięcia „zmień status”, a nie po kwadransie.
• Potwierdzenie płatności — status „opłacone” ma się pojawić od razu po odpowiedzi operatora, inaczej klient dzwoni i pyta, czy pieniądze doszły.
• Nowe konto klienta przekazane do narzędzia marketingowego — mail powitalny wysłany w minutę działa lepiej niż wysłany następnego dnia.

Dwa scenariusze, w których webhook przegrywa:

• Pierwsza masowa synchronizacja katalogu, np. 20 000 produktów. Webhook odpala się per obiekt: dostaniesz 20 000 POST-ów i drugie tyle zapytań po ID. Jednorazowy import przez API, stronami po 100–200 rekordów, pójdzie szybciej i taniej.
• Dobowe raporty sprzedażowe. Liczy się kompletność danych, nie sekunda wysyłki — cron jest prostszy w utrzymaniu.

Kryterium decyzyjne: czy opóźnienie powyżej 5 minut kosztuje Cię pieniądze albo powoduje błędy w stanach magazynowych. Jeśli tak — webhook. Jeśli dane mogą poczekać do nocy — API plus cron. Pozostałe materiały o wdrożeniach zbieramy w dziale PrestaShop.

Gdzie włączyć webhooki w panelu PrestaShop (1.7.1, 8.x, 9.x)

Konfiguracja startuje z zaplecza: Parametry zaawansowane → Webservice → zakładka Webhooki. Zakładka w tej formie jest obecna od wersji 1.7.1 i występuje też w 8.x oraz 9.x, ale nazewnictwo sekcji różni się między wersjami — w jednych instalacjach to osobna zakładka, w innych rozwinięcie bloku Webservice. Zanim cokolwiek ustawisz, sprawdź, czy ją widzisz.

Formularz dodawania webhooka zawiera cztery rzeczy, które realnie wpływają na działanie:

• Nazwa webhooka — etykieta dla Ciebie, np. „ERP – statusy zamówień”. Wpisuj nazwę systemu docelowego, nie „test1”.
• Docelowy URL — adres endpointu, który odbierze POST.
• Wybór hooków z listy — subskrybujesz konkretne zdarzenia, nie „wszystko”.
• Przełącznik trybu real-time vs wysyłka przez cron — decyzja o największych konsekwencjach wydajnościowych w całym artykule.

Tryb real-time oznacza, że żądanie POST leci w tym samym żądaniu HTTP, w którym klient składa zamówienie. Jeśli Twój endpoint odpowie w 4 sekundy zamiast w 0,2, wydłużasz checkout każdemu klientowi w tym samym momencie. Dlatego endpoint musi: być publicznie dostępny po HTTPS z poprawnym certyfikatem, nie blokować metody POST (sprawdź reguły WAF), odpowiadać w czasie do 2 s i zwracać kod 2xx. Czym jest metoda POST i jak działa HTTPS, opisuje dokumentacja MDN Web Docs – HTTP.

Jak sprawdzić, czy funkcja w ogóle jest dostępna: obecność modułu webhooków na liście modułów, uprawnienia pracownika do Parametrów zaawansowanych i brak konfliktu z modułem nadpisującym Hook::exec — o tym, jak bezpiecznie diagnozować takie nadpisania, piszemy w tekście o PrestaShop override.

Pułapka: jeśli natywna wysyłka nie działa, w 9 na 10 przypadków problem jest po stronie odbiorcy (WAF, firewall, 500 w skrypcie), a nie w PrestaShop. Zanim zaczniesz grzebać w sklepie, zaloguj odpowiedź serwera docelowego.

Które hooki subskrybować i co dokładnie leci w payloadzie

Lista hooków jest długa, ale w projektach e-commerce wraca ten sam zestaw ośmiu.

Hook	Kiedy się odpala
actionValidateOrder	Nowe zamówienie po walidacji i zapisie — tu masz id_order
actionOrderStatusUpdate	Przed zapisem zmiany statusu — dane sprzed zmiany
actionOrderStatusPostUpdate	Po zapisie zmiany statusu — właściwy moment na wysyłkę do ERP
actionPaymentConfirmation	Potwierdzenie płatności, np. po callbacku operatora
actionProductUpdate	Zmiana danych produktu po zapisie
actionUpdateQuantity	Zmiana stanu magazynowego, także po sprzedaży
actionCustomerAccountAdd	Rejestracja nowego konta klienta
actionObjectCartAddAfter	Dodanie produktu do koszyka — zdarzenie wysokiej częstotliwości

Najważniejsza różnica: hooki „pre” czytają stan przed zmianą. Jeśli wyślesz status zamówienia do ERP z actionOrderStatusUpdate zamiast z actionOrderStatusPostUpdate, wyślesz dane nieaktualne — i to jest błąd, który wychodzi dopiero po miesiącu, na porównaniu stanów.

Kształt payloadu: JSON z nazwą akcji i parametrami hooka. W większości przypadków dostajesz identyfikatory (id_order, id_product, id_cart), a nie kompletny obiekt — resztę danych musisz dobrać zapytaniem po ID (najlepiej przez Webservice API). Dokumentację hooków znajdziesz w PrestaShop Developer Documentation.

Weryfikacja w 2 minuty: w endpointcie odbiorcy zaloguj surowe body przed parsowaniem — file_get_contents('php://input') do pliku — i złóż jedno testowe zamówienie. Dopiero wtedy wiesz, co realnie wysyła Twoja wersja PrestaShop.

Czego nie ma w natywnej wysyłce: podpisu kryptograficznego, nagłówka autoryzacyjnego i automatycznych ponowień po błędzie. Każde z nich dopisujesz sam.

Multistore: sprawdź, czy w payloadzie dostajesz id_shop. Bez tego webhook z drugiego sklepu nadpisze dane pierwszego. Ciekawym, nietypowym konsumentem zdarzeń ze sklepu jest serwer MCP podłączający AI do danych sklepu.

Własny webhook w module: jak to zrobić dobrze

Natywna konfiguracja webhooka w PrestaShop to zwykłe żądanie HTTP wysłane w trakcie zapytania klienta — bez kolejki, bez retry, bez podpisu. Jeśli integracja ma realne znaczenie (ERP, WMS, system fakturowania), napisz mały moduł. Szkielet: modules/mojmodul/mojmodul.php z klasą MojModul extends Module i metodą install(), w której rejestrujesz hooki: registerHook('actionValidateOrder') oraz registerHook('actionOrderStatusPostUpdate'). Pierwszy łapie nowe zamówienie, drugi — każdą zmianę statusu: płatność potwierdzona, wysłane, anulowane.

Wysyłka: Symfony HttpClient, dostępny w PrestaShop 1.7, 8 i 9. Ustaw timeout 2–3 s oraz max_duration. Całe wywołanie w try/catch — wyjątek wypuszczony z hooka kończy się błędem 500 na stronie koszyka albo potwierdzenia zamówienia. Klient nie zobaczy komunikatu „webhook nie doszedł”, tylko zepsuty sklep.

Krótka synchronizacja to droga do kłopotów. Zdarzenie zapisz do tabeli (ps_mojmodul_queue: id, payload, status, proby, next_attempt, id_order, id_order_state) i wyślij je workerem z crona co minutę. Alternatywa to Symfony Messenger z transportem Doctrine, ale wymaga uruchomionego consumera.

• Idempotencja po stronie odbiorcy: klucz id_order + id_order_state + timestamp. Duplikat ma zwrócić 200 i nic nie robić.
• Retry z backoffem: 1 min, 5 min, 30 min, maksymalnie 5 prób — potem wpis do tabeli błędów i alert.
• Logowanie każdej próby: wysłany payload, kod HTTP odpowiedzi, czas odpowiedzi. Bez tych trzech pól diagnoza jest zgadywaniem.

I jeszcze jedno: zamiast nadpisywać klasy core przez override, oprzyj się na hookach — pokazujemy to w materiale PrestaShop override: jak nadpisywać kod bez błędów. Zasada nadrzędna: jedna odpowiedzialność na webhook. Moduł, który jednocześnie wysyła zamówienie do ERP, wystawia fakturę i wrzuca kontakt do Mailchimp, po awarii jednego odbiorcy blokuje pozostałych. Trzy osobne kolejki diagnozuje się w minutach, jedną wspólną — w godzinach. Sygnatury hooków i kolejność ich wywołania znajdziesz w dokumentacji dla deweloperów PrestaShop.

Bezpieczeństwo: sekret, podpis HMAC i whitelist

Endpoint webhooka jest publicznie dostępny — kto zna adres, wyśle dowolny payload. Minimum: sekret o długości co najmniej 32 bajtów, losowy, trzymany poza repozytorium (zmienna środowiskowa albo plik konfiguracyjny poza katalogiem modułu), i podpis HMAC-SHA256 liczony z surowego body żądania. Podpis wysyłasz w nagłówku, np. X-Signature, razem z X-Timestamp w formacie uniksowym.

Po stronie odbiorcy policz HMAC z body i porównaj przez hash_equals(). Zwykłe == przerywa porównanie na pierwszym różnym bajcie, więc przy dużej liczbie prób da się odtworzyć podpis (atak timingowy). Żądania starsze niż 5 minut odrzucaj — bez tego raz przechwycone żądanie odtworzysz w nieskończoność (replay attack).

Whitelist IP serwera sklepu to druga linia obrony, nie jedyna. IP zmienia się przy migracji hostingu, zmianie CDN albo wyjściu ruchu przez nowy NAT — wtedy webhooki przestają dochodzić, a Ty szukasz przyczyny w PrestaShop. Aktualizuj listę przy każdej zmianie infrastruktury i traktuj ją jako filtr pomocniczy.

• 200 — przyjęte i zapisane do kolejki. 401/403 — zły podpis lub stary timestamp. 500 zwracaj tylko wtedy, gdy naprawdę chcesz powtórkę; natywny PrestaShop i tak nie ponawia, więc 500 bez własnego retry oznacza zgubione zdarzenie.
• Czego nie wysyłać: danych karty, haseł, całych obiektów klienta, jeśli wystarczy id_customer. Dane osobowe w payloadzie to Twoja odpowiedzialność po obu stronach.
• SSRF: jeśli URL webhooka wpisuje użytkownik panelu, waliduj schemat (tylko https) i host. Blokuj 127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 oraz 169.254.169.254. Bez tego ktoś skieruje wysyłkę na wewnętrzny adres sieci i odczyta odpowiedź.

Kody i nagłówki HTTP masz w jednym miejscu — specyfikacja protokołu HTTP w MDN Web Docs. Warto zajrzeć tam przed pisaniem handlera, bo połowa „błędów webhooka” to źle dobrany kod odpowiedzi.

6 awarii, które zdarzają się najczęściej, i jak wykryć je w 10 minut

Zanim zaczniesz grzebać w kodzie, ustal jedno: czy żądanie w ogóle wychodzi ze sklepu. To rozdziela dwie różne klasy problemów — konfigurację po stronie sklepu i zachowanie odbiorcy. Poniższa tabela to kolejność, w jakiej sprawdzamy zgłoszenia.

Objaw	Najczęstsza przyczyna	Test diagnostyczny
Webhook wcale nie leci	Wyjątek PHP w hooku, moduł niezarejestrowany, brak registerHook()	Sprawdź logi błędów PHP na serwerze sklepu i wywołaj endpoint ręcznie przez curl z hosta sklepu, nie z laptopa
403/406	WAF lub mod_security blokuje POST z zewnątrz	Wyślij POST bez ciasteczek z zewnątrz; dodaj wyjątek dla ścieżki endpointu, nie wyłączaj całego WAF
Timeout u odbiorcy	Endpoint wykonuje ciężką operację synchronicznie	Zmierz czas odpowiedzi; powyżej 2 s w trybie real-time odbija się na czasie ładowania koszyka
Duplikaty tego samego zamówienia	Brak idempotencji; klient odświeżył potwierdzenie albo status zmienił się dwukrotnie	Porównaj dwa payloady i sprawdź, czy odbiorca liczy klucz id_order + id_order_state + timestamp
Nieaktualne dane w payloadzie	Użyty hook pre zamiast actionOrderStatusPostUpdate	Porównaj payload z aktualnym stanem zamówienia w panelu po kilkudziesięciu sekundach
Złe ID	Pomylone id_order z reference albo brak obsługi id_shop w multistore	Sprawdź, czy rekord w ERP wskazuje właściwy sklep — przy kilku sklepach ID potrafią się rozjechać

W praktyce najwięcej czasu oszczędza jeden plik CSV: surowe body, kod HTTP odpowiedzi, czas odpowiedzi i timestamp. Po przejrzeniu 20 takich wierszy rozwiązujemy większość zgłoszeń dotyczących webhooków. Jeśli wdrażasz integracje równolegle z innymi, np. z systemem kurierskim, kolejność prac opisujemy w materiale InPost w PrestaShop: wdrożenie krok po kroku. Zbiorczy przegląd tematów sklepowych znajdziesz w sekcji PrestaShop.

Jak webhook nie spowolnił checkoutu

W natywnej konfiguracji wysyłka dzieje się w żądaniu klienta: moduł podpięty do actionValidateOrder wykonuje żądanie HTTP, zanim sklep pokaże potwierdzenie zamówienia. Efekt jest liniowy — jeśli odbiorca odpowiada w 500 ms, składanie zamówienia wydłuża się o 500 ms. Przy 1,5 s u odbiorcy i płatności online klient widzi zawieszoną stronę, a część osób odświeża koszyk i składa zamówienie drugi raz. Każde z tych zdarzeń to osobny webhook i osobny wiersz w ERP.

Stosujemy trzy środki, w tej kolejności:

• Tryb cron. Moduł zapisuje zdarzenie i kończy pracę, a zadanie crona wysyła je co minutę. Dla wysyłki do systemu księgowego czy raportowego opóźnienie do 60 sekund jest zwykle nieistotne.
• Kolejka w bazie i worker. Własny moduł wykonuje jeden INSERT (tabela np. ps_dd_webhook_queue: id, event, payload, idempotency_key, attempts, next_attempt_at) i kończy pracę w kilka milisekund. Worker uruchamiany z CLI przez cron, limit np. 100 rekordów na przebieg, wysyła poza requestem klienta.
• Timeout i circuit breaker. 2 s na pojedyncze żądanie, a po 5 błędach pod rząd wysyłka wyłącza się na 10 minut i tylko loguje. Lepiej stracić kilka zdarzeń z kolejki niż zablokować sprzedaż w piątek wieczorem.

Monitoring: alert, gdy odsetek nieudanych webhooków przekracza 5% albo najstarszy wpis w kolejce ma więcej niż 15 minut. Test kontrolny: 50 zamówień w 5 minut na stagingu i pomiar czasu odpowiedzi koszyka przed i po włączeniu webhooków. Semantykę kodów odpowiedzi i timeoutów opisuje dokumentacja HTTP w MDN. Samą kolejkę budujemy w module, nie przez nadpisywanie rdzenia — opisaliśmy to w materiale PrestaShop override: jak nadpisywać kod bez błędów.

Webhooki w praktyce: ERP, kurierzy, księgowość, marketing

Kurierzy. InPost, DPD i DHL wysyłają statusy przesyłek. Warto mapować je na własne statusy zamówienia, a nie wrzucać jeden do jednego — inaczej klient dostaje maila „Zrealizowane”, gdy paczka dopiero jedzie. Statusów nieznanych nie zgadujemy: lądują w statusie „Do weryfikacji” i logu z pełnym payloadem. Szczegóły integracji z InPost opisujemy w InPost w PrestaShop: wdrożenie krok po kroku, a różnice w nowszej wersji sklepu w InPost i PrestaShop 9: organizacja wdrożenia bez przestojów.

ERP. Subiekt, Comarch, WF-Mag: zamówienie wysyłamy w actionValidateOrder. Jeśli ERP nie odpowiada, zamówienie musi zostać w sklepie z notatką „Czeka na ERP” i trafić do kolejki z retry (1, 5, 15, 60 minut). Nigdy nie usuwamy zamówienia i nigdy nie blokujemy checkoutu.

Księgowość. Webhook z operatora płatności uruchamia wystawienie faktury, ale rozróżniamy płatność oczekującą (autoryzacja) od zaksięgowanej (potwierdzenie od operatora). Faktura tylko dla tej drugiej.

Marketing. actionCustomerAccountAdd i actionValidateOrder do Mailchimp/Klaviyo wysyłamy wyłącznie za zgodą i w minimalnym zakresie: e-mail, imię, ID klienta, wartość zamówienia. Bez danych wrażliwych, z obsługą wypisania się. Przykład integracji, gdzie część funkcji lepiej odpuścić, znajdziesz w Facebook w PrestaShop: co wdrożyć, a co odpuścić.

Kiedy webhook to zły wybór: hurtowa wymiana katalogu i stanów magazynowych. 20 tys. SKU w webhookach to 20 tys. żądań i kolejka rosnąca szybciej, niż worker ją czyści. Tu działa CSV/SFTP albo API z harmonogramem. Definicje hooków znajdziesz w dokumentacji dla deweloperów PrestaShop.

Ile to kosztuje i kiedy warto zrobić to z nami

Widełki, które podajemy przed analizą, są realne dla typowego sklepu na PrestaShop 1.7, 8 lub 9:

• Podstawowy webhook z kolejką, retry i podpisem (HMAC, klucz idempotencji, jeden odbiorca) — 8–16 godzin.
• Integracja z ERP z mapowaniem statusów, obsługą błędów po stronie systemu zewnętrznego i raportem nieudanych zdarzeń — 20–40 godzin.

Na te godziny składa się praca, którą da się wskazać palcem: analiza hooków i struktury danych w Twojej wersji PrestaShop, kod modułu, klucz idempotencji (żeby ponowienie nie zdublowało faktury), testy na stagingu, dokumentacja i przekazanie. Klucz idempotencji to najmniejszy element, a najczęstsza przyczyna „dubli” w ERP.

Liczymy godzinowo, bo liczba hooków i odbiorców zmienia zakres. Cennik „z sufitu” kończy się dopłatami w połowie projektu — a wtedy rozmowa jest już nie o kodzie, tylko o budżecie.

I uczciwie: jeśli potrzebujesz jednego powiadomienia do jednego adresu, natywna konfiguracja z panelu wystarczy i nie ma sensu płacić za moduł. Mówimy to wprost, bo wolimy wrócić przy drugiej integracji niż przepchnąć niepotrzebny projekt.

Po wdrożeniu zostaje opieka: monitoring kolejki, reakcja na błędy po stronie odbiorcy, jasne SLA i kontakt bezpośrednio z deweloperem, bez pośredników. Zakres naszych prac nad sklepem opisuje PrestaShop.

Nie wiesz, czy problem leży po stronie sklepu czy odbiorcy? Wyślij nam logi z ostatnich 24 godzin — wrócimy z diagnozą, bez zobowiązania.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Ustal wersję PrestaShop — Natywna funkcja webhooków jest dostępna od 1.7.1 i występuje też w 8.x oraz 9.x, ale nazwy zakładek różnią się między wersjami — zanim zaczniesz szukać, zanotuj dokładną wersję z panelu.
• Sprawdź uprawnienia pracownika — Konto, na którym pracujesz, musi mieć dostęp do Parametrów zaawansowanych. Brak sekcji to najczęściej kwestia profilu, nie brak funkcji.
• Potwierdź obecność natywnego modułu webhooków — Sprawdź listę modułów. Jeśli modułu nie ma, zweryfikuj, czy inny moduł nie nadpisuje Hook::exec — temat opisujemy w artykule o override w PrestaShop.
• Przygotuj endpoint odbiorcy — Publiczny adres po HTTPS, poprawny certyfikat, brak blokady na metodę POST, odpowiedź w czasie do 2 s.
• Sprawdź certyfikat od zewnątrz — Test z serwera sklepu, nie z przeglądarki. Wygaśnięty lub niepełny łańcuch certyfikatów zablokuje wysyłkę bez czytelnego komunikatu.
• Zmierz czas odpowiedzi endpointu — Kilka prób POST-em, pomiar czasu całkowitego. Wynik powyżej 2 s wyklucza tryb real-time.
• Zdecyduj: real-time czy cron — Real-time tylko wtedy, gdy opóźnienie powyżej 5 minut realnie kosztuje Cię pieniądze lub powoduje błędy w stanach. To najważniejsza decyzja wydajnościowa w całym wdrożeniu.
• Wybierz hooki do subskrypcji — Zacznij od jednego zdarzenia i jednego webhooka. Zamiast zbierać wszystko, wypisz zdarzenia, na które Twój system naprawdę reaguje.
• Ustaw logowanie wysyłek — Każde żądanie zapisuj z czasem, nazwą hooka, payloadem i kodem odpowiedzi. Bez tego nie odróżnisz braku wysyłki od błędu odbiorcy.
• Przetestuj na zamówieniu testowym — Złóż zamówienie od początku do końca i sprawdź, czy zdarzenie dotarło oraz czy dane w systemie docelowym się zgadzają.
• Sprawdź zachowanie przy błędzie odbiorcy — Wyłącz endpoint na kilka minut i sprawdź, czy potrafisz odzyskać brakujące zdarzenia inną drogą. Jeśli nie — zaplanuj kolejkę z ponowieniami.
• Uzgodnij plan rollbacku — Musisz mieć możliwość wyłączenia webhooka jednym przełącznikiem w panelu, bez wdrażania kodu. Sprawdź to przed uruchomieniem na produkcji.
• Porównuj liczby raz dziennie — Zestaw liczbę zdarzeń w sklepie z liczbą zdarzeń w systemie docelowym. Pierwszy tydzień po wdrożeniu — codziennie, potem raz w tygodniu.
• Zapisz konfigurację poza sklepem — Nazwa webhooka, adres docelowy, lista hooków, tryb wysyłki. Przy migracji lub odtwarzaniu sklepu nie ma tego w repozytorium.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• MDN Web Docs – HTTP