Plugin-events eller webhooks? Denne guide forklarer begge mekanismer i Shopware 6 for danske webshops: registrering i manifest.xml, payloadens opbygning, signaturtjek og de hyppigste fejlkilder.
Shopware 6 giver dig to måder at reagere på hændelser i shoppen, og de to bliver let forvekslet. Den ene er det interne PHP-event-system, som plugins kobler sig på, og som kører inde i Shopware-processen. Den anden er webhooks: De hører til app-systemet og giver en ekstern tjeneste besked via HTTP.
Vælger du forkert, koster det tid. En plugin-subscriber kører ikke på en Shopware Cloud-instans, og en webhook kan ikke ændre det, der sker under en request. Denne guide til danske shopejere og udviklere forklarer, hvad de to mekanismer kan, hvordan en webhook registreres og sikres, hvilken adfærd der er dokumenteret, og hvad du ikke bør regne med.
Alle tekniske oplysninger bygger på den officielle udviklerdokumentation fra Shopware. Versionsafhængige funktioner er markeret med den release, de blev introduceret i. Det grundlæggende om platformen finder du på vores side om Shopware-udvikling.
Plugins kører i shoppen. De registrerer en subscriber, der implementerer EventSubscriberInterface, giver den tagget kernel.event_subscriber og modtager events synkront, mens requesten stadig behandles. Fordi subscriberen har fat i event-objektet, kan den påvirke, hvad der sker bagefter: justere en pris, blokere en skrivning eller ændre det, storefronten viser.
Apps kører uden for shoppen. Shopware kommunikerer udelukkende med dem via HTTP, og webhooks er den måde, shoppen fortæller appen, at noget er sket. Appen modtager bagefter en POST-request og reagerer ved at kalde tilbage via Admin API. Den handling, der udløste hændelsen, kan den ikke længere ændre.
En brugbar tommelfingerregel: Skal logikken køre under requesten og ændre resultatet, hører den hjemme i et plugin. Reagerer den bagefter og kører på din egen infrastruktur, hører den hjemme i en app med webhooks. Til simple notifikationer uden egen app er handlingen „Kald URL“ i Flow Builder ofte nok, men den er knyttet til abonnementet Evolve.
Før den første webhook går af, skal fire ting være på plads.
Webhooks hører til en app, ikke til et plugin. Appen beskrives af en manifest.xml og gennemgår et registrerings-handshake med shoppen, hvor din app genererer og gemmer et secret pr. shop. Dette secret signerer senere hver eneste webhook-request.
Leveringen sker via Shopwares message queue. Kører der ingen consumer, bliver beskederne skrevet, men aldrig sendt, og der vises ingen fejl i storefronten. Det er langt den hyppigste årsag til, at en korrekt konfigureret webhook tilsyneladende ikke gør noget.
Shopware sender til den URL, der står i manifestet. Den skal kunne nås fra shopserveren og bør terminere TLS. Til lokal udvikling har du brug for en tunneltjeneste, så shoppen kan nå din maskine.
De fleste webhook-events kræver en tilsvarende rettighed i manifestet. Abonnerer du på order.written uden at deklarere order:read, fejler valideringen. Shopware har tjekket webhook-rettigheder siden version 6.3.5.0.
Der er intet webhook-plugin, der skal installeres. Webhooks deklareres direkte i app-manifestet i en <webhooks>-blok:
<webhooks>
<webhook name="product-changed"
url="https://example.com/event/product-changed"
event="product.written"/>
</webhooks>
Tre attributter er obligatoriske: name skal være entydigt i manifestet, url er det endpoint, Shopware sender til, og event er id’et på det event, du vil modtage.
Kun events, som Shopware markerer som „hookable“, kan bruges. Det dokumenterede sæt dækker de områder, de fleste integrationer har brug for:
checkout.order.placed, order.written, order.deletedproduct.written, product.deleted, customer.written, category.written, media.written og deres modstykkercheckout.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 og de tilsvarende state_leave-eventsapp.installed, app.activated, app.deactivated, app.deleted samt shopware.updatedSiden Shopware 6.5.7.0 kan en webhook have attributten onlyLiveVersion="true". Uden den går en order.written-webhook også af for versionerede kladder, der opstår, når en ordre redigeres i administrationen, og det ønsker en integration normalt ikke:
<webhook name="order-created"
url="https://example.com/event/order-created"
event="order.written"
onlyLiveVersion="true"/>
Attributten bliver kun evalueret ved entity-written-events.
Request-bodyen er JSON og har altid de samme tre nøgler på øverste niveau:
{
"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
}
Ved entity-written-events indeholder payloaden ikke hele entiteten. Shopware begrunder det klart: Fordi leveringen er asynkron, kan en komplet entitet allerede være forældet, når den ankommer. Du får primaryKey, og det forventede mønster er at hente den aktuelle tilstand via Admin API.
Integrationer, der behandler payloaden som sandheden, ender før eller siden med at skrive forældede data tilbage i et tilkoblet system. Den beslutning bør træffes før den første kodelinje, ikke bagefter.
source.shopId identificerer shoppen og er konstant i hele dens levetid.source.eventId er den samme på tværs af genforsøg og er derfor den naturlige nøgle til deduplikering.timestamp er tidspunktet for behandlingen og er tilgængelig fra 6.4.1.0.Derudover sender Shopware fra 6.4.1.0 headeren sw-version og fra 6.4.5.0 sw-context-language og sw-user-language.
Hver webhook-request har headeren shopware-shop-signature. Den indeholder en SHA-256-HMAC over den rå request-body, nøglet med det shop-secret, som din app genererede ved registreringen. Et endpoint, der springer dette tjek over, accepterer alt, hvad hvem som helst sender til det.
App-systemet bruger to forskellige secrets, og forveksles de, er det en hyppig årsag til fejlslagne tjek:
shopware-app-signature signerer query-strengen i registrerings-requesten og bruger det app-secret, du deler med din Shopware-konto.shopware-shop-signature signerer bodyen i webhook-requesten og bruger det shop-secret, der opstår pr. shop ved registreringen.Hash den rå body, før der sker nogen form for JSON-parsing. Frameworks, der serialiserer requesten igen, giver en anden bytefølge og dermed en anden HMAC.
Afvis requests med en for gammel timestamp. En angriber kan ikke ændre tidsstemplet uden at gøre signaturen ugyldig, og derfor er det en brugbar beskyttelse mod genafspillede requests.
Shopware anbefaler at bruge App PHP SDK eller Symfony Bundle i stedet for selv at implementere tjekket. Siden 6.7.13.0 bliver signatur-secret slået op på leveringstidspunktet, så leveringer på tværs af en secret-rotation signeres med det aktuelle secret.
Webhooks fejler lydløst. Intet i storefronten tyder på, at en levering er udeblevet. Første skridt er derfor altid at finde ud af, om Shopware overhovedet har forsøgt.
Shopware logger leveringsforsøg i tabellen webhook_event_log. Er der ingen række for det forventede event, er webhooken aldrig blevet lagt i kø, og problemet ligger i manifestet eller i rettighederne. Er der en række, der aldrig forlader status „queued“, ligger problemet i message queuen, ikke i dit endpoint.
En oprydningsopgave fjerner poster, der er leveret korrekt eller endegyldigt fejlet; poster, der er i gang eller bliver forsøgt igen, bevares. Siden 6.7.4.0 fjernes poster, der hænger i status „queued“, efter den dobbelte konfigurerede opbevaringsperiode.
onlyLiveVersion ikke er sat.Et minimalt endpoint, der logger den rå body og hurtigt svarer med 200, adskiller leveringsproblemer fra behandlingsproblemer. Når leveringerne kommer stabilt frem, flytter du behandlingen bag din egen kø.
De beslutninger, der holder en webhook-integration stabil, træffes tidligt, og de fleste følger af én egenskab: Leveringen er asynkron og kan blive gentaget.
shopware-shop-signature mod den rå body, før noget andet sker.source.eventId er den samme på tværs af genforsøg og afslører en request, der allerede er behandlet.primaryKey.To former for adfærd mangler bevidst på listen, fordi Shopware ikke dokumenterer dem: den præcise HTTP-timeout for en levering, og hvilke statuskoder der regnes som fejl. En integration, der bygger på konkrete værdier, bygger på en antagelse, ikke på en specifikation. Vil du ikke drive din egen app, kan mange webhook-scenarier også løses med en automatiseringsplatform som n8n. Vi hjælper danske webshops med at vælge den rigtige løsning.
Nej. Webhooks hører til app-systemet og deklareres i app-manifestet. Der skal ikke installeres noget fra Shopware Store.
I de fleste tilfælde kører der ingen message queue-consumer. Shopware lægger leveringen i kø og sender den aldrig. Tjek i webhook_event_log, om eventet overhovedet er sat i kø.
Fordi leveringen er asynkron, og en komplet entitet allerede kan være forældet, når den ankommer. Shopware sender primaryKey og forventer, at du henter den aktuelle tilstand via Admin API.
Webhook-dokumentationen nævner ikke et webhook-specifikt tal. Den generelle dokumentation for message queuen siger, at beskeder forsøges tre gange igen, før de flyttes til failure-transporten. Brug det som en størrelsesorden, ikke som en garanti, og dedupliker via source.eventId.
Nej. En webhook er en notifikation bagefter. For at påvirke en igangværende request skal du bruge et plugin med en PHP-event-subscriber, og det kræver til gengæld en selvhostet shop. Hvordan vi udvikler den slags plugins for blandt andre danske forhandlere, viser vi på vores side om udvikling af Shopware-plugins.
Webhooks i app-systemet har været en del af Shopwares kerne siden 6.3-linjen. Enkelte detaljer kom senere: feltet timestamp og headeren sw-version i 6.4.1.0, sprog-headerne i 6.4.5.0 og onlyLiveVersion i 6.5.7.0. Den aktuelle hovedlinje er 6.7.