Zdarzenia wtyczek czy webhooki? Ten przewodnik wyjaśnia oba mechanizmy w Shopware 6, pokazuje rejestrację w manifest.xml, budowę payloadu, weryfikację podpisu i najczęstsze źródła błędów w integracjach sklepów w Polsce.
Shopware 6 oferuje dwa sposoby reagowania na zdarzenia w sklepie i łatwo je ze sobą pomylić. Pierwszy to wewnętrzny system zdarzeń PHP, do którego podłączają się wtyczki i który działa w ramach procesu Shopware. Drugi to webhooki: należą do systemu aplikacji (App System) i powiadamiają zewnętrzną usługę przez HTTP.
Zły wybór kosztuje czas. Subscriber wtyczki nie zadziała w instancji Shopware SaaS (dawniej Shopware Cloud), a webhook nie może zmienić tego, co dzieje się w trakcie żądania. W tym przewodniku wyjaśniamy, co oferują oba mechanizmy, jak zarejestrować i zabezpieczyć webhook, które zachowania są udokumentowane, a na których nie warto polegać. Dotyczy to zwłaszcza sklepów w Polsce, które przez webhooki łączą Shopware z lokalnymi systemami ERP, magazynowymi lub fakturowymi.
Wszystkie informacje techniczne opierają się na oficjalnej dokumentacji deweloperskiej Shopware. Funkcje zależne od wersji oznaczono numerem wydania, w którym zostały wprowadzone. Podstawowe informacje o platformie znajdą Państwo na naszej stronie poświęconej tworzeniu sklepów w Shopware.
Wtyczki działają wewnątrz sklepu. Rejestrują subscriber implementujący EventSubscriberInterface, oznaczają go tagiem kernel.event_subscriber i otrzymują zdarzenia synchronicznie, gdy żądanie jest jeszcze przetwarzane. Ponieważ subscriber ma dostęp do obiektu zdarzenia, może wpłynąć na to, co stanie się dalej: zmienić cenę, zablokować zapis, zmodyfikować wynik w Storefront.
Aplikacje działają poza sklepem. Shopware komunikuje się z nimi wyłącznie przez HTTP, a webhooki są sposobem, w jaki sklep informuje aplikację, że coś się wydarzyło. Aplikacja otrzymuje po fakcie żądanie POST i reaguje, odwołując się z powrotem do Admin API. Nie może już zmienić operacji, która wywołała zdarzenie.
Przydatna reguła: jeśli logika musi działać w trakcie żądania i zmieniać jego wynik, należy do wtyczki. Jeśli reaguje po fakcie i działa na Państwa własnej infrastrukturze, należy do aplikacji z webhookami. Do prostych powiadomień bez własnej aplikacji często wystarczy akcja „Wywołaj URL” we Flow Builderze, która jednak wymaga planu Evolve.
Zanim zostanie wywołany pierwszy webhook, muszą być spełnione cztery warunki.
Webhooki należą do aplikacji, a nie do wtyczki. Aplikację opisuje plik manifest.xml, a ze sklepem przechodzi ona proces rejestracji (handshake), podczas którego Państwa aplikacja generuje i zapisuje sekret dla danego sklepu. Ten sekret podpisuje później każde żądanie webhooka.
Dostarczanie odbywa się przez kolejkę wiadomości (message queue) Shopware. Jeśli żaden konsument nie działa, wiadomości są zapisywane, ale nigdy nie zostają wysłane, a w Storefront nie pojawia się żaden błąd. To zdecydowanie najczęstsza przyczyna, dla której poprawnie skonfigurowany webhook pozornie nic nie robi.
Shopware wysyła żądania na adres URL podany w manifeście. Musi on być osiągalny z serwera sklepu i powinien obsługiwać TLS. Przy pracy lokalnej potrzebna jest usługa tunelująca, aby sklep mógł połączyć się z Państwa komputerem.
Większość zdarzeń webhooków wymaga zadeklarowania odpowiedniego uprawnienia w manifeście. Kto subskrybuje order.written bez deklaracji order:read, nie przejdzie walidacji. Shopware sprawdza uprawnienia webhooków od wersji 6.3.5.0.
Nie trzeba instalować żadnej wtyczki do webhooków. Webhooki deklaruje się bezpośrednio w manifeście aplikacji, w bloku <webhooks>:
<webhooks>
<webhook name="product-changed"
url="https://example.com/event/product-changed"
event="product.written"/>
</webhooks>
Trzy atrybuty są obowiązkowe: name musi być unikalny w obrębie manifestu, url to endpoint, na który Shopware wysyła żądania, a event to identyfikator zdarzenia, które chcą Państwo otrzymywać.
Można korzystać wyłącznie ze zdarzeń oznaczonych przez Shopware jako „hookable”. Udokumentowany zbiór obejmuje obszary potrzebne większości integracji:
checkout.order.placed, order.written, order.deletedproduct.written, product.deleted, customer.written, category.written, media.written i ich odpowiednikicheckout.customer.register, checkout.customer.login, checkout.customer.logout, customer.recovery.requeststate_enter.order.state.completed, state_enter.order_transaction.state.paid, state_enter.order_delivery.state.shipped oraz odpowiadające im zdarzenia state_leaveapp.installed, app.activated, app.deactivated, app.deleted oraz shopware.updatedOd Shopware 6.5.7.0 webhook może mieć atrybut onlyLiveVersion="true". Bez niego webhook order.written uruchamia się także dla wersjonowanych wersji roboczych, które powstają podczas edycji zamówienia w panelu administracyjnym, czego integracja zwykle nie chce:
<webhook name="order-created"
url="https://example.com/event/order-created"
event="order.written"
onlyLiveVersion="true"/>
Atrybut jest uwzględniany tylko przy zdarzeniach typu entity written.
Treść żądania to JSON, który na najwyższym poziomie zawsze ma te same trzy klucze:
{
"data": {
"payload": [
{
"entity": "product",
"operation": "delete",
"primaryKey": "7b04ebe416db4ebc93de4d791325e1d9",
"updatedFields": []
}
],
"event": "product.written"
},
"source": {
"url": "http://localhost:8000",
"appVersion": "0.0.1",
"shopId": "dgrH7nLU6tlE",
"eventId": "7b04ebe416db4ebc93de4d791325e1d9"
},
"timestamp": 123123123
}
W zdarzeniach typu entity written payload nie zawiera pełnej encji. Shopware jasno to uzasadnia: ponieważ dostarczanie jest asynchroniczne, pełna encja mogłaby w chwili dotarcia być już nieaktualna. Otrzymują Państwo primaryKey, a oczekiwanym wzorcem jest pobranie aktualnego stanu przez Admin API.
Integracje, które traktują payload jako źródło prawdy, prędzej czy później zapisują nieaktualne dane w podłączonym systemie. Tę decyzję należy podjąć przed napisaniem pierwszej linii kodu, a nie po.
source.shopId identyfikuje sklep i pozostaje stały przez cały okres jego istnienia.source.eventId pozostaje taki sam przy ponownych próbach, dzięki czemu jest naturalnym kluczem do deduplikacji.timestamp to moment przetworzenia, dostępny od wersji 6.4.1.0.Dodatkowo od wersji 6.4.1.0 Shopware wysyła nagłówek sw-version, a od 6.4.5.0 nagłówki sw-context-language i sw-user-language.
Każde żądanie webhooka zawiera nagłówek shopware-shop-signature. Zawiera on HMAC SHA-256 obliczony z surowej treści żądania przy użyciu sekretu sklepu, który Państwa aplikacja wygenerowała podczas rejestracji. Endpoint, który pomija tę weryfikację, akceptuje wszystko, co ktokolwiek do niego wyśle.
System aplikacji używa dwóch różnych sekretów, a ich pomylenie to częsta przyczyna nieudanej weryfikacji:
shopware-app-signature podpisuje query string żądania rejestracyjnego i korzysta z sekretu aplikacji, który dzielą Państwo ze swoim kontem Shopware.shopware-shop-signature podpisuje treść żądania webhooka i korzysta z sekretu sklepu, który powstaje dla każdego sklepu podczas rejestracji.Hash należy obliczać z surowej treści, zanim nastąpi jakiekolwiek parsowanie JSON. Frameworki, które ponownie serializują żądanie, tworzą inną sekwencję bajtów, a więc i inny HMAC.
Żądania ze zbyt starym timestamp należy odrzucać. Atakujący nie może zmienić znacznika czasu bez unieważnienia podpisu, co czyni go skuteczną ochroną przed ponownym odtwarzaniem żądań.
Shopware zaleca korzystanie z App PHP SDK lub Symfony Bundle zamiast samodzielnej implementacji weryfikacji. Od wersji 6.7.13.0 sekret podpisu jest ustalany w momencie dostarczenia, dzięki czemu dostarczenia po rotacji sekretu są podpisywane aktualnym sekretem.
Webhooki zawodzą po cichu. Nic w Storefront nie wskazuje, że dostarczenie się nie powiodło. Pierwszym krokiem jest więc zawsze ustalenie, czy Shopware w ogóle podjął próbę.
Shopware zapisuje próby dostarczenia w tabeli webhook_event_log. Jeśli brak wiersza dla oczekiwanego zdarzenia, webhook nigdy nie trafił do kolejki, a problem leży w manifeście lub uprawnieniach. Jeśli wiersz istnieje, ale nigdy nie opuszcza statusu „queued”, problem dotyczy kolejki wiadomości, a nie Państwa endpointu.
Zadanie porządkowe usuwa wpisy, które zostały dostarczone lub ostatecznie zakończyły się błędem; wpisy w trakcie przetwarzania lub ponawiane pozostają. Od wersji 6.7.4.0 wpisy zawieszone w statusie „queued” są usuwane po upływie dwukrotności skonfigurowanego okresu przechowywania.
onlyLiveVersion.Minimalny endpoint, który zapisuje surową treść w logu i szybko odpowiada kodem 200, pozwala oddzielić problemy z dostarczaniem od problemów z przetwarzaniem. Gdy dostarczenia docierają niezawodnie, przetwarzanie warto przenieść do własnej kolejki.
Decyzje, które zapewniają stabilność integracji opartej na webhookach, zapadają wcześnie, a większość z nich wynika z jednej cechy: dostarczanie jest asynchroniczne i może być ponawiane.
shopware-shop-signature względem surowej treści, zanim wydarzy się cokolwiek innego.source.eventId pozostaje taki sam przy ponownych próbach i pozwala rozpoznać już przetworzone żądanie.primaryKey.Dwa zachowania celowo pominięto na tej liście, ponieważ Shopware ich nie dokumentuje: dokładny limit czasu HTTP dla dostarczenia oraz to, które kody statusu są traktowane jako błąd. Integracja, która opiera się na konkretnych wartościach, bazuje na założeniu, a nie na specyfikacji. Jeśli nie chcą Państwo utrzymywać własnej aplikacji, wiele scenariuszy z webhookami można zrealizować również przez platformę automatyzacji, taką jak n8n. W polskich projektach typowym przykładem jest przekazanie opłaconego zamówienia do systemu ERP, który wystawia fakturę ustrukturyzowaną w KSeF.
Nie. Webhooki należą do systemu aplikacji i są deklarowane w manifeście aplikacji. Ze Shopware Store nie trzeba niczego instalować.
W większości przypadków nie działa konsument kolejki wiadomości. Shopware umieszcza dostarczenie w kolejce, ale nigdy go nie wysyła. Proszę sprawdzić w webhook_event_log, czy zdarzenie w ogóle trafiło do kolejki.
Ponieważ dostarczanie jest asynchroniczne, a pełna encja mogłaby w chwili dotarcia być już nieaktualna. Shopware wysyła primaryKey i oczekuje, że aktualny stan zostanie pobrany przez Admin API.
Dokumentacja webhooków nie podaje liczby specyficznej dla webhooków. Ogólna dokumentacja kolejki wiadomości mówi, że wiadomości są ponawiane trzykrotnie, zanim trafią do failure transport. Należy traktować to jako rząd wielkości, a nie gwarancję, i deduplikować na podstawie source.eventId.
Nie. Webhook to powiadomienie po fakcie. Aby wpłynąć na trwające żądanie, potrzebna jest wtyczka z subscriberem zdarzeń PHP, co z kolei wymaga sklepu hostowanego samodzielnie. Jak tworzymy takie wtyczki, pokazujemy na stronie o tworzeniu wtyczek Shopware.
Webhooki systemu aplikacji są częścią rdzenia Shopware od linii 6.3. Niektóre szczegóły doszły później: pole timestamp i nagłówek sw-version w 6.4.1.0, nagłówki językowe w 6.4.5.0, a onlyLiveVersion w 6.5.7.0. Aktualna główna linia to 6.7.
Pozwalają przekazywać zamówienia, zmiany statusów i dane produktów do systemów działających poza Shopware, np. polskiego ERP, programu magazynowego, integracji przewoźnika lub narzędzia do faktur w KSeF. Jeśli endpoint zapisuje dane osobowe klientów, jego operator powinien mieć z Państwem umowę powierzenia przetwarzania danych zgodnie z art. 28 RODO. Chętnie pomożemy zaplanować taką integrację dla Państwa sklepu.