Événements de plugin ou webhooks ? Ce guide pour les boutiques en ligne en France explique les deux mécanismes de Shopware 6, l’enregistrement dans le manifest.xml, la structure du payload, la vérification de signature et les erreurs les plus fréquentes.
Shopware 6 offre deux façons de réagir aux événements de la boutique, et on les confond facilement. La première est le système d’événements PHP interne, auquel se greffent les plugins et qui s’exécute dans le processus Shopware. La seconde, ce sont les webhooks : ils font partie du système d’apps et notifient un service externe via HTTP.
Un mauvais choix coûte du temps. Un subscriber de plugin ne fonctionne pas sur une instance Shopware Cloud, et un webhook ne peut pas modifier ce qui se passe pendant une requête. Ce guide, destiné aux équipes techniques des boutiques en ligne françaises, explique ce que permettent les deux mécanismes, comment enregistrer et sécuriser un webhook, quels comportements sont documentés et sur lesquels il ne faut pas compter.
Toutes les indications techniques se réfèrent à la documentation officielle des développeurs Shopware. Les fonctionnalités dépendant d’une version sont signalées avec la release qui les a introduites. Les bases de la plateforme sont présentées sur notre page consacrée au développement Shopware.
Les plugins s’exécutent dans la boutique. Ils enregistrent un subscriber qui implémente EventSubscriberInterface, lui attribuent le tag kernel.event_subscriber et reçoivent les événements de manière synchrone, pendant que la requête est encore en cours de traitement. Comme le subscriber dispose de l’objet événement, il peut influencer la suite : ajuster un prix, bloquer une écriture, modifier le rendu de la storefront.
Les apps s’exécutent en dehors de la boutique. Shopware communique avec elles exclusivement via HTTP, et les webhooks sont le moyen par lequel la boutique informe l’app qu’un événement s’est produit. L’app reçoit a posteriori une requête POST et réagit en rappelant l’Admin API. Elle ne peut plus modifier l’opération à l’origine de l’événement.
Une règle empirique utile : si la logique doit s’exécuter pendant la requête et en modifier le résultat, elle a sa place dans un plugin. Si elle réagit après coup et tourne sur votre propre infrastructure, elle a sa place dans une app avec webhooks. Pour de simples notifications sans app dédiée, l’action « Appeler une URL » du Flow Builder suffit souvent ; elle est toutefois liée au plan Evolve.
Avant que le premier webhook ne se déclenche, quatre éléments doivent être en place.
Les webhooks appartiennent à une app, pas à un plugin. L’app est décrite par un fichier manifest.xml et effectue avec la boutique un handshake d’enregistrement, au cours duquel votre app génère et stocke un secret par boutique. Ce secret signera ensuite chaque requête de webhook.
La livraison passe par la Message Queue de Shopware. Si aucun consumer ne tourne, les messages sont écrits mais jamais envoyés, et aucune erreur n’apparaît dans la storefront. C’est de loin la cause la plus fréquente pour laquelle un webhook correctement configuré semble ne rien faire.
Shopware envoie la requête à l’URL indiquée dans le manifeste. Elle doit être accessible depuis le serveur de la boutique et devrait terminer TLS. Pour le développement local, vous avez besoin d’un service de tunnel afin que la boutique puisse atteindre votre machine.
La plupart des événements de webhook exigent une permission correspondante dans le manifeste. Celui qui s’abonne à order.written sans déclarer order:read échoue à la validation. Shopware vérifie les permissions des webhooks depuis la version 6.3.5.0.
Il n’y a aucun plugin de webhook à installer. Les webhooks se déclarent directement dans le manifeste de l’app, dans un bloc <webhooks> :
<webhooks>
<webhook name="product-changed"
url="https://example.com/event/product-changed"
event="product.written"/>
</webhooks>
Trois attributs sont obligatoires : name doit être unique au sein du manifeste, url est le point de terminaison auquel Shopware envoie la requête, et event est l’identifiant de l’événement que vous souhaitez recevoir.
Seuls les événements que Shopware marque comme « hookable » peuvent être utilisés. L’ensemble documenté couvre les domaines dont la plupart des intégrations ont besoin :
checkout.order.placed, order.written, order.deletedproduct.written, product.deleted, customer.written, category.written, media.written et leurs équivalentscheckout.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 et les événements state_leave correspondantsapp.installed, app.activated, app.deactivated, app.deleted ainsi que shopware.updatedDepuis Shopware 6.5.7.0, un webhook peut porter l’attribut onlyLiveVersion="true". Sans cet attribut, un webhook order.written se déclenche aussi pour les brouillons versionnés créés lors de la modification d’une commande dans l’administration, ce qu’une intégration ne souhaite généralement pas :
<webhook name="order-created"
url="https://example.com/event/order-created"
event="order.written"
onlyLiveVersion="true"/>
L’attribut n’est évalué que pour les événements de type entity written.
Le corps de la requête est au format JSON et comporte toujours les trois mêmes clés de premier 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
}
Pour les événements de type entity written, le payload ne contient pas l’entité complète. Shopware le justifie clairement : la livraison étant asynchrone, une entité complète pourrait déjà être obsolète à son arrivée. Vous recevez la primaryKey, et le schéma attendu consiste à recharger l’état actuel via l’Admin API.
Les intégrations qui traitent le payload comme source de vérité finissent tôt ou tard par réécrire des données obsolètes dans un système connecté. Cette décision doit être prise avant la première ligne de code, pas après.
source.shopId identifie la boutique et reste constant pendant toute sa durée de vie.source.eventId reste identique d’une tentative à l’autre et constitue donc la clé naturelle de déduplication.timestamp correspond au moment du traitement et est disponible depuis la 6.4.1.0.Shopware envoie en outre l’en-tête sw-version depuis la 6.4.1.0, ainsi que sw-context-language et sw-user-language depuis la 6.4.5.0.
Chaque requête de webhook porte l’en-tête shopware-shop-signature. Il contient un HMAC SHA-256 calculé sur le corps brut de la requête, avec pour clé le secret de boutique que votre app a généré lors de l’enregistrement. Un point de terminaison qui omet cette vérification accepte tout ce que n’importe qui lui envoie.
Le système d’apps utilise deux secrets différents, et les confondre est une cause fréquente d’échec de vérification :
shopware-app-signature signe la query string de la requête d’enregistrement et utilise le secret d’app que vous partagez avec votre compte Shopware.shopware-shop-signature signe le corps de la requête de webhook et utilise le secret de boutique créé pour chaque boutique lors de l’enregistrement.Hachez le corps brut avant tout parsing JSON. Les frameworks qui resérialisent la requête produisent une autre suite d’octets et donc un autre HMAC.
Rejetez les requêtes dont le timestamp est trop ancien. Un attaquant ne peut pas modifier l’horodatage sans invalider la signature, ce qui en fait une protection efficace contre les requêtes rejouées.
Shopware recommande d’utiliser l’App PHP SDK ou le Symfony Bundle plutôt que d’implémenter soi-même la vérification. Depuis la 6.7.13.0, le secret de signature est résolu au moment de la livraison, de sorte que les livraisons effectuées pendant une rotation du secret sont signées avec le secret actuel.
Les webhooks échouent en silence. Rien dans la storefront n’indique qu’une livraison n’a pas eu lieu. La première étape consiste donc toujours à déterminer si Shopware a seulement essayé.
Shopware consigne les tentatives de livraison dans la table webhook_event_log. S’il n’existe aucune ligne pour l’événement attendu, le webhook n’a jamais été mis en file d’attente et le problème se situe dans le manifeste ou les permissions. S’il existe une ligne qui ne quitte jamais le statut « queued », le problème vient de la Message Queue, pas de votre point de terminaison.
Une tâche de nettoyage supprime les entrées livrées avec succès ou définitivement en échec ; les entrées en cours ou en nouvelle tentative sont conservées. Depuis la 6.7.4.0, les entrées bloquées au statut « queued » sont supprimées après le double de la durée de conservation configurée.
onlyLiveVersion n’est pas défini.Un point de terminaison minimal qui journalise le corps brut et répond rapidement avec un code 200 permet de distinguer les problèmes de livraison des problèmes de traitement. Dès que les livraisons arrivent de façon fiable, déplacez le traitement derrière votre propre file d’attente.
Les décisions qui assurent la stabilité d’une intégration par webhooks se prennent tôt, et la plupart découlent d’une seule caractéristique : la livraison est asynchrone et peut être répétée.
shopware-shop-signature sur le corps brut avant toute autre opération.source.eventId reste identique d’une tentative à l’autre et permet de reconnaître une requête déjà traitée.primaryKey.Deux comportements sont volontairement absents de cette liste, car Shopware ne les documente pas : le timeout HTTP exact d’une livraison et les codes de statut considérés comme des erreurs. Une intégration qui s’appuie sur des valeurs concrètes repose sur une hypothèse, pas sur une spécification. Si vous ne souhaitez pas exploiter votre propre app, de nombreux scénarios de webhooks peuvent aussi être réalisés avec une plateforme d’automatisation comme n8n.
Non. Les webhooks font partie du système d’apps et sont déclarés dans le manifeste de l’app. Rien n’est à installer depuis le Shopware Store.
Dans la plupart des cas, aucun consumer de Message Queue ne tourne. Shopware met la livraison en file d’attente et ne l’envoie jamais. Vérifiez dans webhook_event_log si l’événement a seulement été mis en file.
Parce que la livraison est asynchrone et qu’une entité complète pourrait déjà être obsolète à son arrivée. Shopware envoie la primaryKey et attend que vous chargiez l’état actuel via l’Admin API.
La documentation des webhooks n’indique pas de valeur spécifique. La documentation générale de la Message Queue précise que les messages sont retentés trois fois avant de passer dans le failure transport. Considérez cela comme un ordre de grandeur, pas comme une garantie, et dédupliquez via source.eventId.
Non. Un webhook est une notification a posteriori. Pour influencer une requête en cours, il vous faut un plugin avec un subscriber d’événements PHP, ce qui suppose une boutique auto-hébergée. Nous présentons notre façon de développer ces plugins sur notre page consacrée au développement de plugins Shopware.
Les webhooks du système d’apps font partie du cœur de Shopware depuis la ligne 6.3. Certains détails sont arrivés plus tard : le champ timestamp et l’en-tête sw-version en 6.4.1.0, les en-têtes de langue en 6.4.5.0 et onlyLiveVersion en 6.5.7.0. La ligne principale actuelle est la 6.7.
Vous préparez une intégration par webhooks pour votre boutique en France, par exemple vers un ERP, un transporteur ou un outil CRM ? Notre équipe vous aide à choisir entre app et plugin et à sécuriser les flux de données.