¿Eventos de plugin o webhooks? Esta guía para tiendas online en España explica ambos mecanismos en Shopware 6, el registro en el manifest.xml, la estructura del payload, la comprobación de la firma y las causas de error más frecuentes.
Shopware 6 ofrece dos formas de reaccionar a los eventos de la tienda, y es fácil confundirlas. Una es el sistema interno de eventos de PHP, en el que se enganchan los plugins y que se ejecuta dentro del proceso de Shopware. La otra son los webhooks: pertenecen al sistema de apps y notifican a un servicio externo mediante HTTP.
Elegir mal cuesta tiempo. Un subscriber de un plugin no se ejecuta en una instancia de Shopware Cloud, y un webhook no puede modificar lo que ocurre durante una petición. Esta guía, dirigida a equipos técnicos de tiendas online en España, explica qué ofrece cada mecanismo, cómo se registra y protege un webhook, qué comportamientos están documentados y en cuáles no conviene confiar.
Todos los datos técnicos se basan en la documentación oficial para desarrolladores de Shopware. Las funciones que dependen de la versión indican la release en la que se introdujeron. Encontrará los fundamentos de la plataforma en nuestra página sobre desarrollo con Shopware.
Los plugins se ejecutan dentro de la tienda. Registran un subscriber que implementa EventSubscriberInterface, lo etiquetan con kernel.event_subscriber y reciben los eventos de forma síncrona mientras la petición todavía se está procesando. Como el subscriber tiene en sus manos el objeto del evento, puede influir en lo que ocurre a continuación: ajustar un precio, bloquear una escritura o modificar la salida de la Storefront.
Las apps se ejecutan fuera de la tienda. Shopware se comunica con ellas exclusivamente mediante HTTP, y los webhooks son la vía por la que la tienda comunica a la app que algo ha ocurrido. La app recibe a posteriori una petición POST y reacciona llamando de vuelta a través de la Admin API. Ya no puede modificar el proceso que lo originó.
Una regla práctica útil: si la lógica debe ejecutarse durante la petición y modificar su resultado, va en un plugin. Si reacciona a posteriori y vive en su propia infraestructura, va en una app con webhooks. Para notificaciones sencillas sin app propia, a menudo basta con la acción «Llamar a URL» del Flow Builder, aunque está vinculada al plan Evolve.
Antes de que se dispare el primer webhook, deben estar listas cuatro cosas.
Los webhooks pertenecen a una app, no a un plugin. La app se describe mediante un manifest.xml y realiza con la tienda un handshake de registro, en el que su app genera y guarda un secret por tienda. Ese secret firmará después cada petición de webhook.
La entrega se realiza a través de la cola de mensajes de Shopware. Si no hay ningún consumer en marcha, los mensajes se escriben pero nunca se envían, y en la Storefront no aparece ningún error. Es, con diferencia, la causa más frecuente de que un webhook bien configurado parezca no hacer nada.
Shopware envía a la URL indicada en el manifiesto. Debe ser accesible desde el servidor de la tienda y debería terminar TLS. Para el desarrollo local necesita un servicio de túnel para que la tienda llegue a su equipo.
La mayoría de los eventos de webhook requieren el permiso correspondiente en el manifiesto. Quien se suscribe a order.written sin declarar order:read no supera la validación. Shopware comprueba los permisos de los webhooks desde la versión 6.3.5.0.
No hay ningún plugin de webhooks que instalar. Los webhooks se declaran directamente en el manifiesto de la app, dentro de un bloque <webhooks>:
<webhooks>
<webhook name="product-changed"
url="https://example.com/event/product-changed"
event="product.written"/>
</webhooks>
Hay tres atributos obligatorios: name debe ser único dentro del manifiesto, url es el endpoint al que envía Shopware y event es el identificador del evento que desea recibir.
Solo pueden usarse los eventos que Shopware marca como «hookable». El conjunto documentado cubre las áreas que necesitan la mayoría de las integraciones:
checkout.order.placed, order.written, order.deletedproduct.written, product.deleted, customer.written, category.written, media.written y sus equivalentescheckout.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 y los eventos state_leave correspondientesapp.installed, app.activated, app.deactivated, app.deleted, así como shopware.updatedDesde Shopware 6.5.7.0, un webhook puede llevar el atributo onlyLiveVersion="true". Sin este atributo, un webhook order.written se dispara también para los borradores versionados que se generan al editar un pedido en la administración, algo que normalmente una integración no quiere:
<webhook name="order-created"
url="https://example.com/event/order-created"
event="order.written"
onlyLiveVersion="true"/>
El atributo solo se evalúa en los eventos entity-written.
El cuerpo de la petición es JSON y siempre tiene las mismas tres claves en el nivel superior:
{
"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
}
En los eventos entity-written, el payload no contiene la entidad completa. Shopware lo justifica con claridad: como la entrega es asíncrona, una entidad completa podría estar ya desactualizada al llegar. Usted recibe el primaryKey, y el patrón esperado es volver a cargar el estado actual a través de la Admin API.
Las integraciones que tratan el payload como fuente de verdad acaban escribiendo, tarde o temprano, datos obsoletos en un sistema conectado. Esta decisión debe tomarse antes de la primera línea de código, no después.
source.shopId identifica la tienda y se mantiene constante durante toda su vida útil.source.eventId se mantiene igual en los reintentos y es, por tanto, la clave natural para la deduplicación.timestamp es el momento del procesamiento y está disponible desde 6.4.1.0.Además, Shopware envía desde 6.4.1.0 la cabecera sw-version y desde 6.4.5.0 las cabeceras sw-context-language y sw-user-language.
Cada petición de webhook lleva la cabecera shopware-shop-signature. Contiene un HMAC SHA-256 del cuerpo bruto de la petición, calculado con el secret de la tienda que su app generó durante el registro. Un endpoint que omite esta comprobación acepta cualquier cosa que alguien le envíe.
El sistema de apps utiliza dos secrets distintos, y confundirlos es una causa frecuente de comprobaciones fallidas:
shopware-app-signature firma el query string de la petición de registro y utiliza el secret de la app que usted comparte con su cuenta de Shopware.shopware-shop-signature firma el cuerpo de la petición de webhook y utiliza el secret de la tienda, que se genera por tienda durante el registro.Calcule el hash del cuerpo bruto antes de cualquier parseo de JSON. Los frameworks que vuelven a serializar la petición generan otra secuencia de bytes y, por tanto, otro HMAC.
Rechace las peticiones con un timestamp demasiado antiguo. Un atacante no puede modificar la marca de tiempo sin invalidar la firma, lo que la convierte en una protección útil contra peticiones repetidas.
Shopware recomienda utilizar el App PHP SDK o el Symfony Bundle en lugar de implementar la comprobación por cuenta propia. Desde 6.7.13.0, el secret de firma se resuelve en el momento de la entrega, de modo que las entregas posteriores a una rotación del secret se firman con el secret vigente.
Los webhooks fallan en silencio. Nada en la Storefront indica que una entrega no se ha producido. Por eso, el primer paso siempre es determinar si Shopware llegó a intentarlo.
Shopware registra los intentos de entrega en la tabla webhook_event_log. Si no hay ninguna fila para el evento esperado, el webhook nunca se puso en cola, y el problema está en el manifiesto o en los permisos. Si hay una fila que nunca sale del estado «queued», el problema está en la cola de mensajes, no en su endpoint.
Una tarea de limpieza elimina las entradas entregadas correctamente o que han fallado definitivamente; las que están en curso o en reintento se conservan. Desde 6.7.4.0, las entradas atascadas en el estado «queued» se eliminan una vez transcurrido el doble del periodo de conservación configurado.
onlyLiveVersion.Un endpoint mínimo que registre el cuerpo bruto y responda rápidamente con 200 separa los problemas de entrega de los de procesamiento. En cuanto las entregas lleguen de forma fiable, traslade el procesamiento a una cola propia.
Las decisiones que mantienen estable una integración con webhooks se toman pronto, y la mayoría se derivan de una propiedad: la entrega es asíncrona y puede repetirse.
shopware-shop-signature contra el cuerpo bruto antes de hacer cualquier otra cosa.source.eventId se mantiene igual en los reintentos y permite reconocer una petición ya procesada.primaryKey a través de la Admin API.customer.written o de pedidos) a un ERP, a un CRM o a la integración con transportistas como Correos, SEUR o MRW, cargue solo los campos necesarios y formalice con cada proveedor externo un contrato de encargado del tratamiento conforme al art. 28 del RGPD. En España, la autoridad de control es la AEPD.En esta lista faltan deliberadamente dos comportamientos, porque Shopware no los documenta: el timeout HTTP exacto de una entrega y qué códigos de estado se consideran error. Una integración que dependa de valores concretos se basa en una suposición, no en una especificación. Si no desea operar una app propia, muchos escenarios de webhook pueden resolverse también con una plataforma de automatización como n8n.
No. Los webhooks pertenecen al sistema de apps y se declaran en el manifiesto de la app. No hay que instalar nada desde la Shopware Store.
En la mayoría de los casos, porque no hay ningún consumer de la cola de mensajes en marcha. Shopware pone la entrega en cola y nunca la envía. Compruebe en webhook_event_log si el evento llegó a ponerse en cola.
Porque la entrega es asíncrona y una entidad completa podría estar desactualizada al llegar. Shopware envía el primaryKey y espera que usted cargue el estado actual a través de la Admin API.
La documentación de webhooks no indica una cifra específica. La documentación general de la cola de mensajes señala que los mensajes se reintentan tres veces antes de pasar al failure transport. Tómelo como orden de magnitud, no como garantía, y deduplique mediante source.eventId.
No. Un webhook es una notificación a posteriori. Para influir en una petición en curso necesita un plugin con un event subscriber de PHP, lo que a su vez requiere una tienda autoalojada. Mostramos cómo desarrollamos este tipo de plugins en nuestra página sobre desarrollo de plugins para Shopware; si su tienda opera en España y necesita conectar sistemas externos, podemos ayudarle a elegir el enfoque adecuado.
Los webhooks del sistema de apps forman parte del núcleo de Shopware desde la línea 6.3. Algunos detalles llegaron más tarde: el campo timestamp y la cabecera sw-version en 6.4.1.0, las cabeceras de idioma en 6.4.5.0 y onlyLiveVersion en 6.5.7.0. La línea principal actual es la 6.7.