Webhooki w Shoperze – jak automatyzować procesy zamówień

Weryfikacja i bezpieczeństwo webhooków

Adres URL webhooka jest publiczny, więc teoretycznie każdy może wysłać na niego dane. Dlatego skrypt musi sprawdzić, czy request naprawdę pochodzi z Twojego sklepu. Według przykładowego skryptu w pomocy Shopera request zawiera m.in. nagłówki X-Webhook-ID, X-Webhook-SHA1, X-Webhook-Name i X-Shop-Domain. Skrypt oblicza skrót SHA1 z identyfikatora webhooka, klucza i treści requestu, a następnie porównuje go z wartością nagłówka X-Webhook-SHA1.

• Zawsze ustawiaj klucz – pole jest opcjonalne, ale bez niego nie zweryfikujesz autentyczności danych.

• Odrzucaj requesty z błędną sumą – nie przetwarzaj danych, jeśli skrót się nie zgadza.

• Używaj HTTPS – według pomocy szyfrowanie danych zapewnia certyfikat SSL po stronie odbiorcy.

• Przechowuj klucz bezpiecznie – nie wpisuj go na stałe w kodzie w publicznym repozytorium.

• Loguj requesty – zapisuj identyfikator i wynik przetwarzania, aby łatwo diagnozować problemy.

[#uwaga] Przykładowy skrypt z pomocy Shopera jest materiałem poglądowym – m.in. ma klucz wpisany na stałe i po błędnej weryfikacji tylko zapisuje komunikat w logu, ale nie przerywa przetwarzania. Nie uruchamiaj go na produkcji bez poprawek. Skrypt produkcyjny powinien odrzucać nieprawidłowe requesty i obsługiwać błędy.

Procesy zamówień, które warto zautomatyzować webhookami

Webhooki najlepiej sprawdzają się tam, gdzie liczy się czas reakcji albo gdzie zdarzenie w sklepie powinno uruchomić pracę w innym systemie.

• Przekazanie zamówienia do magazynu – opłacone zamówienie od razu trafia do systemu magazynowego lub operatora fulfillmentu.

• Dokumenty sprzedaży – sygnał dla zewnętrznego programu, że trzeba wystawić dokument.

• Powiadomienia dla zespołu – informacja o dużym lub nietypowym zamówieniu na komunikatorze firmowym.

• CRM i marketing – nowy klient trafia do systemu sprzedaży, gdzie dalsze działania zależą od jego zgód.

• Raporty w czasie rzeczywistym – zdarzenia zapisywane w arkuszu lub hurtowni danych.

Wykres – przykładowe automatyzacje oparte na webhookach. [#chart:sh36b]

Zanim zbudujesz automatyzację na webhookach, sprawdź, co da się ustawić w samym panelu: automatyczne zmiany statusów, wiadomości e-mail i reguły zamówień. Opisujemy je w artykułach automatyzacja zamówień w Shoperze i powiadomienia e-mail i SMS w Shoperze.

[#przyklad] Sklep z kawą współpracuje z firmą fulfillmentową. Wcześniej pracownik co godzinę eksportował opłacone zamówienia i wysyłał plik do magazynu. Po wdrożeniu webhooka na zdarzenie opłacenia zamówienia skrypt odbiera dane, weryfikuje sumę SHA1, przekazuje zamówienie do systemu operatora i zapisuje wynik w logu. Zamówienia trafiają do kompletacji w ciągu minut, a nie godzin.

Jak zaprojektować niezawodną obsługę webhooków

Idempotencja brzmi technicznie, ale chodzi o prostą rzecz: jeśli to samo zamówienie przyjdzie dwa razy, system zewnętrzny powinien je rozpoznać po identyfikatorze i nie tworzyć drugiego zlecenia wysyłki. Tego typu zabezpieczenia oddzielają integrację „działającą na demo” od takiej, która bezpiecznie przetrwa Black Friday.

Webhooki a gotowe aplikacje i integracje

Wiele aplikacji z App Store korzysta z webhooków i API „pod spodem” – instalujesz je i konfigurujesz bez pisania kodu. Własne webhooki mają sens, gdy łączysz sklep z systemem, dla którego nie ma gotowej aplikacji, albo potrzebujesz nietypowej logiki. Gotowe rozwiązania przeglądamy w artykule Shoper App Store – przydatne aplikacje, a integracje z ERP – w tekście Shoper i Subiekt.

Jeśli rozważasz oddanie magazynu firmie zewnętrznej, przeczytaj też artykuł fulfillment dla sklepu Shoper. Przy rosnącej liczbie zamówień przydadzą się wskazówki z tekstu skalowanie sklepu na Shoperze.

Pierwszy webhook krok po kroku – scenariusz testowy

1. Wybierz jeden proces – np. przekazanie opłaconych zamówień do magazynu.

2. Przygotuj adres testowy – w serwisie do przechwytywania requestów wygeneruj tymczasowy URL.

3. Utwórz webhook – wpisz adres, zaznacz jedno zdarzenie, wybierz format i ustaw klucz.

4. Złóż zamówienie testowe – opłać je testową płatnością lub ręcznie zmień status zgodnie z procedurą sklepu.

5. Sprawdź dane – zobacz, jakie pola przyszły, i porównaj je z wymaganiami systemu docelowego.

6. Przekaż specyfikację programiście – na tej podstawie powstaje skrypt produkcyjny z weryfikacją i logami.

7. Podmień adres na produkcyjny – po testach wpisz docelowy URL i obserwuj zakładkę Historia przez pierwsze dni.

Taki scenariusz pozwala uniknąć sytuacji, w której programista pisze kod „w ciemno”, a dopiero po wdrożeniu okazuje się, że brakuje pola potrzebnego magazynowi albo format adresu nie pasuje do systemu kuriera.

Dane osobowe w webhookach

Webhooki dotyczące zamówień i klientów przenoszą dane osobowe: imiona i nazwiska, adresy, telefony, e-maile. Odbiorca webhooka staje się więc kolejnym miejscem przetwarzania tych danych. Upewnij się, że serwer docelowy jest zabezpieczony, dostęp do logów mają tylko uprawnione osoby, a dane nie są przechowywane dłużej, niż to konieczne. Jeśli odbiorcą jest firma zewnętrzna, np. operator magazynu, zadbaj o odpowiednią umowę powierzenia przetwarzania danych.

Te same zasady dotyczą dostępów do panelu i API – opisujemy je w artykułach bezpieczeństwo sklepu na Shoperze oraz uprawnienia administratorów w Shoperze.

Najczęstsze błędy przy webhookach

• Brak klucza i weryfikacji – skrypt przyjmuje dowolne dane wysłane na publiczny adres.

• Zbyt wiele zdarzeń – webhook wysyłany przy każdej drobnej zmianie zalewa serwer requestami.

• Długie przetwarzanie w trakcie requestu – skrypt nie odpowiada na czas, a dane trzeba ponawiać.

• Brak obsługi duplikatów – ponowiony request tworzy drugie zlecenie w magazynie.

• Nikt nie patrzy w historię – błędy widoczne w zakładce Historia pozostają niezauważone tygodniami.

• Nieaktywny webhook – po zapisaniu zapomniano zaznaczyć Aktywność.

Najczęściej zadawane pytania

Gdzie w Shoperze ustawić webhook?

W panelu w sekcji Aplikacje i integracje > Webhooki (w starszym panelu Dodatki i integracje > Webhooki). Klikasz Dodaj webhook, podajesz adres URL, zdarzenia, format i klucz, zaznaczasz Aktywność i zapisujesz.

W jakim formacie Shoper wysyła dane webhooka?

Format wybierasz w formularzu webhooka. Przykładowy skrypt w pomocy Shopera obsługuje dane w formacie JSON i XML.

Jak sprawdzić, czy webhook pochodzi z mojego sklepu?

Ustaw klucz w formularzu i weryfikuj sumę kontrolną. Według przykładu w pomocy skrypt liczy SHA1 z identyfikatora webhooka, klucza i treści requestu i porównuje go z nagłówkiem X-Webhook-SHA1.

Czy mogę ponownie wysłać webhook?

Tak. W edycji webhooka, w zakładce Historia, widzisz wysłane requesty i możesz ręcznie wysłać je ponownie.

Czy do webhooków potrzebuję programisty?

Konfiguracja w panelu jest prosta, ale pod adresem URL musi działać skrypt, który odbierze i przetworzy dane. Zwykle przygotowuje go programista albo udostępnia go narzędzie zewnętrzne.

Gdzie znajdę listę zdarzeń webhooków?

W dokumentacji webhooków na developers.shoper.pl. Pomoc Shopera podaje jako przykłady opłacenie zamówienia i rejestrację klienta.

Podsumowanie

Webhooki w Shoperze pozwalają reagować na zdarzenia w sklepie w ciągu sekund: przekazać opłacone zamówienie do magazynu, dodać klienta do CRM czy powiadomić zespół. Konfiguracja w panelu zajmuje kilka minut, ale o sukcesie decyduje skrypt po drugiej stronie – z weryfikacją klucza, obsługą duplikatów, kolejką zadań i monitoringiem. Zacznij od jednego zdarzenia, przetestuj je na serwisie do przechwytywania requestów, a dopiero potem buduj kolejne automatyzacje.

Jeśli chcesz zautomatyzować obsługę zamówień webhookami i API bez ryzyka zgubionych zamówień, pomożemy zaprojektować i wdrożyć integrację – sprawdź ofertę wdrożenia i rozwoju sklepu Shoper.