Webhooki dla zamówień — po co i dla kogo?

Najszybszy sposób na aktualne dane o sprzedaży w ERP i mniej ręcznej roboty po obu stronach.

Webhooki dla zamówień to prosty mechanizm, dzięki któremu Twój sklep internetowy automatycznie „puka” do ERP za każdym razem, gdy dzieje się coś ważnego: złożono nowe zamówienie, zmienił się jego status, zaktualizowano płatność albo zwrot. Zamiast odpytywać sklep co kilka minut i przerzucać pliki CSV, system ERP dostaje natychmiastowe powiadomienie z danymi, a następnie aktualizuje stany magazynowe, dokumenty sprzedażowe, płatności czy wysyłki. To oszczędza czas, minimalizuje błędy i sprawia, że klienci szybciej otrzymują potwierdzenia i informacje o realizacji.

Jeśli rośnie Ci sprzedaż, a zespół zaczyna tonąć w powtarzalnych czynnościach, webhooki są często pierwszym krokiem do stabilnej, skalowalnej integracji między sklepem a ERP. Dobra wiadomość: wdrożenie da się zrobić etapami i bez wielkiej rewolucji w architekturze IT.

Jak działają powiadomienia webhooks od kuchni

Sklep wysyła zdarzenie HTTP do Twojego ERP – ERP potwierdza odbiór i przetwarza dane.

• Zdarzenie: w sklepie zachodzi akcja (np. „order.created”, „order.updated”, „order.fulfilled”, „refund.created”).
• Wysłanie: platforma e-commerce wykonuje żądanie HTTP POST na wskazany przez Ciebie adres URL (tzw. endpoint).
• Format: zwykle JSON z danymi zamówienia, klienta, produktów, płatności, dostawy oraz identyfikatorem zdarzenia.
• Odpowiedź: Twój ERP powinien szybko zwrócić status 2xx (np. 200 OK) – to sygnał „odebrałem, przetworzę”.
• Ponowienia: jeśli ERP nie odpowie lub zwróci błąd, większość platform spróbuje wysłać zdarzenie ponownie.

Kluczowe jest, aby ERP był gotowy na przyjęcie i bezpieczne przetworzenie takiej wiadomości: walidacja podpisu (jeśli dostępna), idempotentność (przetworzenie zdarzenia tylko raz), kolejka zadań i monitoring.

Przygotowanie ERP: endpoint, bezpieczeństwo, niezawodność

Najpierw zbuduj solidny „port odbiorczy”, dopiero potem włączaj powiadomienia w sklepie.

• Adres URL (endpoint) do odbioru powiadomień: np. /api/webhooks/orders
• Autoryzacja:
  • Podpis HMAC/SHA wysyłany w nagłówku przez sklep (waliduj po stronie ERP).
  • Dodatkowy token w nagłówku (np. Bearer) lub klucz w bezpiecznej zmiennej środowiskowej.
  • Opcjonalnie allowlist IP platformy.
• Idempotentność: nadawaj każdemu zdarzeniu unikalny identyfikator i zapisuj go po przetworzeniu, by zignorować duplikaty.
• Kolejki i „retry”: odbierz zdarzenie, zapisz do kolejki (np. RabbitMQ, SQS, Redis), odpowiedz 200 i przetwarzaj asynchronicznie.
• Limity: chroń ERP przed „burzą” zdarzeń poprzez throttling i backoff.
• Observability: logi, metryki, alerty – wiesz od razu, gdy webhooki przestaną dochodzić lub rośnie liczba błędów.

To podejście „najpierw odbierz i potwierdź, potem przetwarzaj” znacząco podnosi niezawodność i skraca czas odpowiedzi.

Konfiguracja w popularnych platformach

Krok po kroku: gdzie kliknąć i co włączyć, aby strumień zdarzeń ruszył.

WooCommerce (WordPress)

Szybka konfiguracja w panelu, wsparcie dla podpisów i testów.

• Ustawienia > Zaawansowane > Webhooki > Dodaj webhook.
• Wybierz temat zdarzenia (np. „Order created”, „Order updated”).
• Wklej URL endpointu ERP i ustaw format na JSON.
• Włącz stan „Aktywny”.
• Skonfiguruj klucz tajny (secret) – WooCommerce podpisuje payload HMAC SHA256 (nagłówek: X-WC-Webhook-Signature).
• Przetestuj wysyłkę: możesz wymusić ponowną dostawę z poziomu listy webhooków.

Shopify

Bogate zdarzenia, silne bezpieczeństwo, świetne narzędzia do testów.

• Ustawienia > Notyfikacje > Webhooki > Dodaj.
• Wybierz zdarzenia: Orders Create/Updated/Paid/Fulfilled/Cancelled/Refunds.
• Podaj URL ERP.
• Zapisz „Secret” do weryfikacji HMAC (nagłówek: X-Shopify-Hmac-Sha256).
• Sprawdź logi dostaw i wymuś retrysy z panelu.
• Rozważ webhook topics z App Store, jeśli potrzebujesz specyficznych zdarzeń.

Shopware 6

Elastyczność i dobra dokumentacja dla integracji headless.

• Przejdź do Integrations > Webhooks.
• Dodaj URL i wybierz eventy order/checkout.
• Skonfiguruj nagłówki autoryzacyjne i sekrety.
• Zweryfikuj dostawy w Activity/Logs.

Magento 2 / Adobe Commerce

Czasem przez rozszerzenia – ale potrafi bardzo dużo.

• Magento nie ma „czystych” webhooków dla wszystkich przypadków; często stosuje się moduły integracyjne (np. Magespecialist, Webhook API).
• Wybierz rozszerzenie z podpisami i retry, skonfiguruj eventy orders/invoices/shipments.
• Sprawdź cron i kolejki – to podstawa w Magento.

PrestaShop

Najczęściej przez moduł – zweryfikuj wsparcie dla podpisów.

• Zainstaluj moduł webhooków zgodny z Twoją wersją.
• Wybierz zdarzenia zamówień i ustaw sekrety.
• Przetestuj na środowisku staging.

W każdym przypadku ustaw środowisko testowe (staging) z danymi testowymi i oddzielnymi sekretami. Nigdy nie zaczynaj od produkcji.

Webhooki dla zamówień — jakie dane i jak je mapować

Ustal jednoznaczną „mapę” pól, by ERP przetwarzał zamówienia bez ręcznych korekt.

Najczęściej przekazywane pola to:

• Identyfikator zamówienia w sklepie, numer zamówienia (często różne rzeczy)
• Status (np. pending, paid, cancelled, fulfilled)
• Dane klienta i adresy (rozbij na pola: imię, nazwisko, ulica, miasto, kod, kraj, telefon, e-mail)
• Pozycje: SKU, nazwa, ilość, cena, VAT, rabaty
• Płatność: metoda, status, identyfikator transakcji
• Dostawa: metoda, koszt, przewoźnik, numer śledzenia
• Sumy: netto, VAT, brutto, waluta, kurs (jeśli wielowalutowość)
• Metadane: źródło sprzedaży, kampania, kody rabatowe

Dobre praktyki:

• Zachowuj oryginalne identyfikatory ze sklepu jako referencje w ERP.
• Zadbaj o zgodność stawek VAT i nazw stawek między systemami.
• Ustal politykę zaokrągleń – różne platformy potrafią liczyć ceny od netto/brutto i rozkładać rabaty inaczej.
• Jeśli ERP wymaga istnienia produktów przed przyjęciem zamówienia, przygotuj mechanizm fallback (np. tworzenie produktu tymczasowego) lub wcześniejszą synchronizację katalogu.

Synchronizacja w dwie strony: co z aktualizacją statusów i stanów

Nie tylko przyjmuj dane – odsyłaj kluczowe zmiany z ERP do sklepu.

• Po wystawieniu faktury w ERP zaktualizuj zamówienie w sklepie (status „invoiced/paid”).
• Po kompletacji i nadaniu przesyłki odeślij numer śledzenia i przewoźnika.
• Synchronizuj stany magazynowe – najlepiej w oparciu o kolejkę i batchowe aktualizacje, by nie zabić API sklepu.
• Przy zwrotach i korektach – wyślij do sklepu odpowiednie aktualizacje, aby klient widział spójny status.

Dwukierunkowość często łączy webhooki (ze sklepu) z wywołaniami API (z ERP do sklepu). Zaplanuj to świadomie, aby uniknąć pętli aktualizacji.

Bezpieczeństwo: podpisy, tokeny, IP i RODO

Najpierw zaufanie, potem automatyzacja.

• Weryfikuj podpisy HMAC nad payloadem. Bez tego każdy mógłby wysłać fałszywe zamówienie.
• Przechowuj sekrety w bezpiecznym miejscu (zmienne środowiskowe, manager tajemnic).
• Rozważ listę dozwolonych IP platformy (jeśli dostępna i stabilna).
• Szyfruj transmisję (HTTPS wymóg), logi pseudonimizuj.
• Zgodność z RODO: trzymaj tylko potrzebne dane, ustaw retencję, ogranicz dostęp operacyjny.
• Nigdy nie loguj pełnych numerów kart czy poufnych tokenów płatniczych.

Niezawodność: błyskawiczna odpowiedź i przetwarzanie w tle

Odpowiadaj 200 szybko, a ciężką pracę rób asynchronicznie.

• Odbierz, zweryfikuj podpis, zapisz do kolejki i od razu wyślij 200 OK.
• Przetwarzaj payload w workerach – możesz skalować je horyzontalnie.
• Wprowadź „dead-letter queue” dla zdarzeń problematycznych i automatyczne powiadomienia (e-mail/Slack).
• Ustal polityki retry z backoff (np. 1m, 5m, 15m) i limit prób.
• Idempotentność to must-have: nawet 10 identycznych zdarzeń nie może utworzyć 10 faktur.

Testy i monitoring: mniej niespodzianek w produkcji

Sprawdź wszystko na stagingu, zanim ruszysz na żywo.

• Scenariusze testowe: nowe zamówienie, anulowanie, płatność opóźniona, częściowa realizacja, zwrot.
• Testuj „brudne” przypadki: produkt bez SKU, znak specjalny w adresie, brak numeru telefonu, waluta inna niż domyślna.
• Mierz czas od zdarzenia w sklepie do aktualizacji w ERP.
• Monitoruj: liczba zdarzeń, błędy, opóźnienia, topologie retrysów.
• Przeglądaj logi podpisów – od razu widać nieudane weryfikacje.

Webhooki dla zamówień — najczęstsze błędy i jak ich uniknąć

Kilka pułapek, które wracają jak bumerang.

• Brak walidacji podpisu – podatność na nadużycia.
• Przetwarzanie synchroniczne – przekroczenia timeoutów i kaskada błędów.
• Brak idempotentności – duplikaty dokumentów i chaos w księgowości.
• Zbyt rozbudowane payloady – ERP nie potrzebuje wszystkiego; filtruj i waliduj.
• Nieprzemyślana zmiana statusów – pętle aktualizacji między ERP a sklepem.
• Brak wersjonowania schematu – drobna zmiana po stronie sklepu psuje parser w ERP.

Aby temu zapobiec: wprowadź kontrakt API (schemat, wersja), testy integracyjne i proces wdrażania zmian w trybie „feature flags”.

Roadmapa wdrożenia bez bólu

Małe kroki, szybkie sukcesy, jasne mierniki jakości.

1. Zmapuj procesy: które statusy w sklepie mają jakie odpowiedniki w ERP.
2. Przygotuj endpoint ERP: bezpieczeństwo, kolejki, logowanie.
3. Włącz webhooki tylko dla „order.created” na stagingu, przetestuj end-to-end.
4. Dodaj kolejne zdarzenia: płatności, wysyłki, zwroty.
5. Włącz monitoring i alerty.
6. Rollout na produkcję w oknach niskiego ruchu.
7. Retrospektywa po tygodniu: czasy, błędy, wąskie gardła – iteruj.

Pytania, które warto zadać zanim zaczniesz

Dobra analiza na starcie oszczędza godziny gaszenia pożarów.

• Jakie dokładnie zdarzenia mają uruchamiać synchronizację?
• Które pola są krytyczne z perspektywy ERP (obowiązkowe vs. opcjonalne)?
• Co robimy, gdy brakuje produktu w ERP – tworzymy placeholder, czy odrzucamy zamówienie?
• Jak długo trzymamy logi i payloady (RODO, audyt)?
• Kto dostaje alert, gdy padnie odbiór webhooków o 2 w nocy?
• Jak zabezpieczamy się przed przeciążeniem (limity, backpressure, skalowanie workerów)?

Podsumowanie: od pierwszego webhooka do przewidywalnej integracji

Prosty mechanizm, duża wartość – pod warunkiem, że zadbasz o podstawy.

Webhooki to szybka i sprawdzona metoda przekazywania informacji o zamówieniach między sklepem a ERP. Aby działały bezproblemowo, skoncentruj się na trzech filarach: bezpieczeństwo (podpisy, HTTPS, kontrola dostępu), niezawodność (kolejki, retry, idempotentność) oraz czytelny kontrakt danych (mapowanie pól, wersjonowanie). Zacznij od jednego zdarzenia, przeprowadź solidne testy i dopiero potem poszerzaj zakres. Dzięki temu Twoje zamówienia będą spójne, dokumenty w ERP pojawią się na czas, a zespół przestanie walczyć z ręczną synchronizacją i skupi się na obsłudze klientów.