Jak skonfigurować webhooki WooCommerce

Webhooki w sklepie WooCommerce pozwalają automatycznie przekazywać informacje o zdarzeniach w sklepie — np. nowych zamówieniach czy zmianach produktów — do innych systemów. Dzięki temu integracje działają niemal w czasie rzeczywistym, bez konieczności cyklicznego odpytywania API. Ten przewodnik prowadzi krok po kroku przez konfigurację, zabezpieczenie i testy, tak aby niezawodnie przesyłać dane do własnych usług, narzędzi CRM, ERP czy automatyzacji marketingu.

Jak działają webhooki i przygotowanie do pracy

Co to jest webhook w kontekście WooCommerce

Webhook to mechanizm wysyłania HTTP POST przez sklep, gdy wystąpi określone zdarzenie (np. utworzenie zamówienia). WooCommerce tworzy i wysyła komunikat do wskazanego adresu URL, nazywanego adresatem lub technicznie: endpoint. W treści żądania otrzymujesz ustrukturyzowany payload (zwykle JSON) oraz nagłówki pozwalające zweryfikować źródło i integralność danych. Dzięki temu możesz natychmiast zareagować: zaktualizować magazyn w ERP, uruchomić wysyłkę, wystawić fakturę czy dopisać klienta do kampanii.

Wymagania wstępne: domena, certyfikat SSL i dostęp

Przed konfiguracją przygotuj: działającą stronę ze sklepem i panelem administracyjnym, adres publiczny odbiorcy (np. app.mojadomena.pl/webhooks/wc), ważny certyfikat SSL (HTTPS), aby dane w drodze były szyfrowane, oraz możliwość wprowadzania zmian w serwerze lub aplikacji odbierającej. Jeśli nie masz jeszcze gotowego odbiornika, możesz tymczasowo użyć usług inspekcji żądań (Webhook.site, RequestBin) albo tunelu developerskiego (np. ngrok), aby łatwo podejrzeć treść trafiających zgłoszeń.

Struktura przepływu i odpowiedzialności

Architektura jest prosta: WooCommerce (źródło) emituje wywołanie HTTP do Twojej usługi (odbiorca). Za niezawodność odpowiadacie obie strony: WooCommerce ponawia dostawę przy błędach (w rozsądnych granicach), natomiast odbiorca powinien szybko odpowiadać poprawnym statusem HTTP i przetwarzać dane w sposób idempotentny. Dobrą praktyką jest rozdzielić przyjęcie żądania od właściwego przetwarzania: po odebraniu danych zapisz je w kolejce i natychmiast zwróć 200 OK, a cięższe operacje wykonaj asynchronicznie.

Konfiguracja webhooków w WooCommerce krok po kroku

Nawigacja do ustawień i dodanie webhooka

W panelu WordPress przejdź do: WooCommerce → Ustawienia → Zaawansowane → Webhooki. Kliknij Dodaj webhook. Otworzy się formularz, w którym określisz nazwę, status, typ zdarzenia, adres dostarczenia i dane uwierzytelniające. Po zapisaniu WooCommerce utworzy webhook i zacznie wysyłać żądania natychmiast po zajściu wskazanych zdarzeń.

Omówienie pól konfiguracji

• Nazwa: opisowe określenie celu (np. „ERP – nowe zamówienia”).
• Status: aktywny lub wstrzymany. Najpierw możesz dodać webhook jako wstrzymany, przetestować, a następnie aktywować.
• Temat (Event): wybór wyzwalacza (np. order.created, order.updated, product.updated, coupon.created). W zależności od potrzeb możesz utworzyć kilka wyspecjalizowanych webhooków, zamiast jednego „do wszystkiego”.
• Adres dostarczenia (Delivery URL): publiczny URL Twojej usługi przyjmującej żądania. Pamiętaj o HTTPS.
• Format: zazwyczaj JSON. To domyślny i najwygodniejszy wybór do integracji.
• Sekret: ciąg znaków używany do podpisywania wiadomości. Zapisz go bezpiecznie – posłuży do weryfikacji autentyczności. W dalszej części pokażemy, jak użyć go do weryfikacji HMAC.
• Wersja API: zwykle najnowsza dostępna wersja sklepu. Zmiana wersji może zmienić strukturę danych.

Dobór zdarzeń i strategia rozdzielenia przepływów

Nie łącz wszystkich przypadków w jednym webhooku. Utwórz osobne wpisy dla krytycznych procesów: jedno dla tworzenia zamówień, inne dla ich aktualizacji, a kolejne dla zmian w produktach. Dzięki temu uprościsz kod po stronie odbiorcy i łatwiej odseparujesz błędy. Jeśli Twój system końcowy potrzebuje pełnego stanu, rozważ odbieranie tylko zdarzeń powstania i aktualizacji, a kasowanie obsługiwać przez dodatkową synchronizację okresową.

Przykład: powiadomienia o nowym zamówieniu

Utwórz webhook „ERP – nowe zamówienia”. Ustaw Status: aktywny; Temat: order.created; Format: JSON; Adres dostarczenia: https://integracja.twojadomena.pl/wc/orders; Sekret: wygeneruj losowy, długi ciąg. Zapisz. Od tej chwili każde nowe zamówienie spowoduje wysyłkę danych pod wskazany URL. Po stronie odbiorcy dodasz logikę zapisania zamówienia i uruchomisz kolejne kroki (np. rezerwację stanów).

Kiedy WooCommerce wysyła i ponawia żądania

WooCommerce wywołuje webhook bezpośrednio po zdarzeniu, a jeśli napotka błąd (np. timeout, 4xx/5xx), podejmuje ponowne próby w rosnących odstępach. Precyzyjny harmonogram zależy od wersji i konfiguracji, ale ogólna zasada brzmi: jeśli Twój odbiorca regularnie zwraca błąd, sklep będzie powtarzał dostawę ograniczoną liczbę razy, po czym oznaczy ją jako nieudaną. Dlatego tak istotne jest szybkie przyjęcie i krótka odpowiedź 2xx, a cięższe działania przenieś na tło.

Podgląd dzienników i ponowne wysyłki

W WooCommerce → Status → Logi znajdziesz dzienniki dotyczące webhooków i API. W widoku pojedynczego webhooka dostępna jest historia dostaw, kody odpowiedzi i możliwość ręcznego ponowienia wywołania. To najprostszy sposób, aby sprawdzić, czy Twój serwer przyjmuje zgłoszenia i czy odpowiadasz właściwym statusem HTTP.

Projekt i zabezpieczenie odbiornika (endpointu)

Minimalny odbiornik: szybkie przyjęcie i zapis

Odbiornik powinien jak najszybciej przyjąć żądanie, zweryfikować nagłówki i podpisać wiarygodność, a następnie zapisać dane do kolejki (np. Redis, RabbitMQ, SQS) lub do tabeli „inbox” w bazie. Odpowiedz 200 OK w ciągu kilkuset milisekund. Takie podejście chroni przed przekroczeniami czasu i zwiększa niezawodność, gdy systemy zależne (ERP, e-mail, fakturowanie) są chwilowo obciążone.

Weryfikacja podpisu HMAC i nagłówków

Każde żądanie zawiera nagłówek X-WC-Webhook-Signature, który jest podpisem bazującym na mechanizmie HMAC i sekrecie ustawionym w webhooku. Implementacja weryfikacji:

• Weź surowe ciało żądania (dokładnie takie, jakie przyszło na gnieździe HTTP).
• Oblicz HMAC-SHA256 z użyciem klucza „sekretu”.
• Zakoduj wynik w base64.
• Porównaj czasowo-bezpiecznie z wartością z nagłówka X-WC-Webhook-Signature.

Jeśli podpis się nie zgadza, zwróć 401 lub 403. Jest to kluczowe, aby żaden nieautoryzowany podmiot nie mógł wstrzyknąć spreparowanych danych do Twojej integracji. Pamiętaj, by sekret przechowywać w bezpieczny sposób (np. w menedżerze sekretów) i rotować go co jakiś czas.

Idempotencja i deduplikacja

Webhooki mogą być dostarczone wielokrotnie (np. po błędzie sieci). Zaimplementuj idempotencję: użyj identyfikatora zdarzenia z nagłówków (np. X-WC-Webhook-Delivery-ID) lub pól w treści i zapisuj obrócone już identyfikatory. Jeśli takie samo zgłoszenie dotrze ponownie, pomiń kosztowne operacje i po prostu zwróć 200 OK. Uchroni Cię to przed podwójnym wystawieniem faktury czy zdublowaniem zamówień.

Uprawnienia, autoryzacja i ochrona warstwy sieci

Poza podpisem HMAC zadbaj o dodatkowe zabezpieczenia: ogranicz dostęp do endpointu na poziomie zapory (allowlist), jeśli posiadasz przewidywalny zakres adresów IP (w praktyce bywa to trudne), filtruj metodę HTTP (dopuszczaj tylko POST), ustaw limity żądań (rate limiting), blokuj żądania o nadmiernym rozmiarze, a w razie potrzeby dodaj własną warstwę autoryzacjay (np. własny token w nagłówku). Korzystaj z wymuszonego HTTPS i aktualnych protokołów TLS.

Kody odpowiedzi i obsługa błędów

• 200/204: żądanie przyjęte. To preferowany rezultat, gdy poprawnie zapiszesz zgłoszenie do kolejki lub bazy.
• 400/422: nieprawidłowe dane – stosuj oszczędnie, zwykle lepiej logować i przyjąć, bo część pól może się zmieniać między wersjami API.
• 401/403: podpis niepoprawny lub brak uprawnień.
• 500/503: błąd po Twojej stronie. WooCommerce potraktuje to jako wezwanie do ponowienia dostawy (patrz retry), ale nie nadużywaj tej ścieżki.

Przykładowy kształt payloadu i mapowanie

Dla order.created WooCommerce zwykle wysyła obiekt z danymi zamówienia: identyfikator, status, pozycje, kwoty, dane klienta, adresy, metody płatności i wysyłki, pola meta. Zmapuj te pola na encje po swojej stronie. Ustal, które są krytyczne (ID zamówienia, waluta, kwoty brutto/netto, SKU pozycji), a które są pomocnicze (notatki, meta). Trzymaj się zasady: przetwarzaj to, co potrzebne, resztę zachowuj w logach lub archiwum na wypadek sporów.

Testowanie, diagnostyka i monitoring

Testy lokalne: ngrok, Webhook.site, RequestBin

Podczas tworzenia odbiornika przydają się narzędzia do inspekcji: Webhook.site lub RequestBin pokażą Ci nagłówki i ciało żądania, abyś zweryfikował, co dokładnie wysyła WooCommerce. Z kolei ngrok umożliwia wystawienie lokalnego serwera na publiczny HTTPS (z własnym publicznym URL), co pozwala debugować kod w IDE. Pamiętaj o weryfikacji podpisu także w środowisku developerskim.

Wysyłka testowa i powtórna z panelu

W edycji webhooka możesz uruchomić ponowną dostawę dla ostatnich zdarzeń. Skorzystaj z tego, gdy poprawisz błąd po swojej stronie i chcesz szybko przetestować nową wersję. Obserwuj statusy w historii dostaw i kody odpowiedzi. Brak 2xx oznacza, że odbiornik dalej ma problem (np. timeout, błąd weryfikacji podpisu, błędny Content-Type).

Najczęstsze problemy i ich rozwiązania

• Timeouty: skróć czas do odpowiedzi, wprowadź kolejkę i asynchroniczne przetwarzanie.
• Błąd podpisu: upewnij się, że używasz dokładnie tego samego „sekretu” co w konfiguracji webhooka i liczysz podpis na surowym ciele żądania, zanim parser JSON wprowadzi zmiany.
• Nieprawidłowy Content-Type: spodziewaj się application/json; zwracaj poprawny Content-Type w odpowiedzi, choć WooCommerce wymaga głównie statusu 2xx.
• Duże zamówienia: wprowadź limit rozmiaru ciała i skalowanie pionowe/poziome dla usług przyjmujących; jeśli to konieczne, rozważ stronicowanie przez REST API w kroku asynchronicznym.
• Duplikaty: włącz idempotencję i deduplikację po identyfikatorze dostawy lub hashach treści.
• Zmiany wersji API: przypnij wersję w webhooku i testuj zmianę na środowisku testowym przed produkcją.

Monitoring produkcyjny i alertowanie

Zaimplementuj metryki: liczba przyjętych żądań, średni czas odpowiedzi, odsetek błędów, liczba ponowień. Wysyłaj alerty, gdy rośnie liczba niepowodzeń. Po stronie WooCommerce okresowo sprawdzaj logi i statusy webhooków. W razie utraty pakietów (np. dłuższa awaria) możesz zsynchronizować stan przez REST API sklepu, pobierając zmienione zasoby od zadanej daty.

Scenariusze użycia i dobre praktyki

ERP, realizacja zamówień i dokumenty

Gdy klient złoży zamówienie, webhook order.created natychmiast przekazuje dane do systemu ERP: rezerwujesz stany, generujesz dokument WZ, inicjujesz etykiety przewoźników. Po opłaceniu (order.updated → status paid/processing) wystawiasz fakturę i wysyłasz ją e-mailem. Jeśli zamówienie jest anulowane, aktualizujesz rezerwacje i stany. Dzięki temu łańcuch dostaw działa spójnie, a klient szybciej otrzymuje informację o statusie.

Aktualizacja stanów i cen

Webhooki product.updated oraz product.deleted ułatwiają synchronizację katalogu między sklepem a PIM/ERP. Po wykryciu zmiany SKU, stanów, cen – odbiornik aktualizuje dane w systemach zależnych. Dla dużych katalogów łącz podejście push (webhook) z okresową walidacją przez REST API, aby wychwycić ewentualne pominięte zdarzenia.

Marketing automation i CRM

Po order.created dodaj kontakt do CRM z odpowiednim segmentem; po order.updated (status completed) uruchom reguły scoringowe i follow-up. Pamiętaj o zgodach marketingowych i minimalizacji danych – przekazuj tylko to, co konieczne. Jeśli gromadzisz dane w zewnętrznych narzędziach, zabezpiecz przepływy zgodnie z wytycznymi RODO (szyfrowanie w spoczynku i w tranzycie, kontrola dostępu, retencja).

Audyt, zgodność i prywatność

Loguj metadane dostaw (id dostawy, id zdarzenia, znacznik czasu, kod odpowiedzi). Nie przechowuj niepotrzebnie pełnych danych osobowych; zamiast tego stosuj pseudonimizację i skrócony zakres pól. Zapewnij użytkownikom prawa dostępu i usunięcia – jeśli webhooki trafiają do zewnętrznych usług, przygotuj mechanizmy przekazania żądań usunięcia.

Wydajność i skalowanie

Oddziel przyjęcie żądania od przetwarzania ciężkiego (kolejka + konsument). Skaluj horyzontalnie instancje odbiornika za load balancerem. Zadbaj o idempotencję przy wieloinstancyjności. Stosuj backpressure (limity kolejek) i mechanizmy dead-letter dla błędnych wiadomości. W razie skoków ruchu (promocje, święta) zwiększ zasoby i podnieś limity połączeń.

Implementacja: przykładowe kroki i wskazówki techniczne

Tworzenie odbiornika w WordPress (wtyczka) lub poza nim

Możesz przyjmować webhooki zarówno w ramach WordPressa (np. przez dedykowany endpoint w wtyczce i rejestrowanie własnej trasy), jak i w niezależnej usłudze (np. Node.js, Python, PHP-FPM, Go). W przypadku WordPressa pamiętaj o zminimalizowaniu narzutu (wyłącz zbędne hooki, ładuj minimum kodu), aby czas odpowiedzi był krótki. W usługach zewnętrznych łatwo zastosujesz lekkie frameworki i kolejki.

Weryfikacja podpisu: kroki obliczeniowe

• Odczytaj nagłówki: X-WC-Webhook-Signature, X-WC-Webhook-Topic, X-WC-Webhook-Resource, X-WC-Webhook-Delivery-ID.
• Uzyskaj surowe ciało (raw body) bez modyfikacji.
• signature = base64( HMAC_SHA256( raw_body, secret ) ).
• Porównaj signature z nagłówkiem (czasowo-bezpieczne porównanie, unikaj wrażliwości na timing attack).

Jeśli walidacja kończy się niepowodzeniem, loguj próbę i zwracaj 401/403. Tylko poprawnie podpisane żądania trafiają dalej do kolejki.

Model danych i mapowanie pól

Wprowadź pośredni model „EventEnvelope”: delivery_id, topic, resource, czas, hash treści, dane surowe. Na tej podstawie twórz komendy aplikacyjne (CreateOrder, UpdateOrder, UpdateStock). Zmniejsza to sprzężenie z formatem WooCommerce, ułatwia wersjonowanie i testy.

Obsługa ponowień i strategia retry

Po Twojej stronie zaprojektuj politykę ponowień dla integracji downstream (np. ERP). Jeśli ERP nie odpowiada, zapisz wiadomość do kolejki opóźnionej i spróbuj ponownie według strategii wykładniczej z jitterem. Oddziel to od mechanizmu sklepu: nawet jeśli WooCommerce przestanie powtarzać dostawę, Twoja kolejka i tak będzie próbować dostarczyć komunikat do ERP zgodnie z własną polityką retry.

Walidacja schematu i odporność na zmiany

Zaimplementuj lekki walidator pól krytycznych (np. id, total, currency, line_items[].sku, quantity). Jeśli brakuje pól niekrytycznych, nie przerywaj przetwarzania; loguj ostrzeżenia. Dzięki temu małe zmiany w formacie nie zatrzymają produkcji. Wersjonuj mapowanie i testuj przynajmniej na sandboxie lub środowisku staging przy aktualizacjach WooCommerce i wtyczek.

Bezpieczeństwo operacyjne

Upewnij się, że klucze i sekrety są trzymane w bezpiecznych magazynach (KMS, Vault), aktualizujesz biblioteki kryptograficzne, wymuszasz HTTPS i najnowsze TLS. Projektuj ograniczenia dostępu (RBAC) do panelu sklepu i samego odbiornika, a także mechanizmy rotacji haseł i sekretów. Prowadź audyt zmian konfiguracji webhooków (kto dodał, co zmienił, kiedy).

Przykładowy przebieg end-to-end

1) Klient składa zamówienie. 2) WooCommerce emituje event order.created i wysyła POST do Twojego adresu. 3) Odbiornik weryfikuje podpis HMAC przy użyciu wartości „sekretu”, zapisuje EventEnvelope i odpowiada 200 OK. 4) Konsument kolejki tworzy zamówienie w ERP, aktualizuje magazyn, generuje etykietę i fakturę. 5) Po sukcesie system wysyła potwierdzenie do klienta i zapisuje log audytowy. 6) W razie błędu ERP, komunikaty trafiają do kolejki opóźnionej i podejmowane są ponowienia zgodnie z polityką.

Checklist przed produkcją

• Certyfikat SSL ważny i poprawnie zainstalowany.
• Weryfikacja podpisu i limit rozmiaru ciała żądania.
• Idempotencja po delivery_id i/lub hash treści.
• Kolejka + krótka odpowiedź 2xx w odbiorniku.
• Monitoring metryk i alerty błędów.
• Logi diagnostyczne z korelacją (delivery_id).
• Testy scenariuszy: nowe zamówienie, aktualizacja, anulowanie, duże zamówienie, błędny podpis.
• Procedura rotacji sekretu i aktualizacji wersji API.

Stosując powyższe kroki i wzorce, wdrożysz stabilny przepływ o niskich opóźnieniach, odporny na błędy sieciowe i różnice w formatach. Twoje integracje będą reagować natychmiast, dane pozostaną spójne, a procesy operacyjne staną się mierzalne i łatwe do skalowania.