Documentación de Zeyvro n8n Connector para PrestaShop

Versión 1.3.9 · Actualizado el 29-09-2026 · Probado en PrestaShop 8.0.5, 8.1.7, 8.2.6, 9.0.0 y 9.1.3 · PHP 8.1 a 8.4

Documentación de Zeyvro n8n Connector: cómo instalarlo, qué eventos envía tu tienda a n8n y en qué formato, cómo comprobar en n8n que vienen de tu tienda, qué puede pedirle n8n a la tienda por el webhook entrante y qué hacer cuando algo no llega.

Qué hace el módulo

Conecta tu tienda PrestaShop con n8n en los dos sentidos, sin programar el envío ni la firma.

1. 8 eventos de salida. Pedido nuevo, cambio de estado de pedido, cliente nuevo, cliente actualizado, producto nuevo, producto actualizado, cambio de stock y carrito.
2. Firma HMAC. Cada envío lleva la cabecera X-Zeyvro-Signature y, si lo configuras, un token fijo en X-Webhook-Token.
3. Activación por evento. Enciendes solo los eventos que usa tu workflow.
4. Webhook entrante. n8n puede actualizar stock, cambiar el estado de un pedido, crear un cliente o consultar un pedido.
5. Registro y reenvío. Cada envío queda con su código HTTP y los fallidos se reenvían desde el back office.
6. Prueba de conexión. Un botón envía un evento de prueba y muestra el código HTTP que devuelve tu n8n.

Instalación

1. Back office → Módulos → Gestor de módulos → Subir un módulo.
2. Selecciona zeyvro_n8nconnector-1.3.9.zip y espera a que termine.
3. Pulsa Configurar en el módulo. Además, el módulo añade al menú Zeyvro → n8n Connector, donde está el registro de envíos.

No hay clave que introducir. El módulo funciona en cuanto se instala: no pide clave de activación.

Al instalarse deja el módulo activado, los 8 eventos marcados, el registro de envíos encendido, 1 intento por envío y un secreto generado para la firma. Solo falta la URL de tu webhook de n8n.

Configuración

La página Configurar del módulo empieza con una guía rápida plegable y cinco cifras: total enviados, exitosos, errores, hoy y tasa de éxito.

Configuración general

Campo	Qué hace
Activar módulo	Si está desmarcado, no se envía ningún evento a n8n.
URL del Webhook n8n	La Production URL del nodo Webhook de tu workflow (método POST), la que contiene /webhook/.
Token estático (opcional)	Si lo rellenas, cada envío añade la cabecera X-Webhook-Token con ese valor, además de la firma.
Reintentos en fallo	1, 2, 3 o 5 intentos por envío. Entre intento e intento espera 1 s, 2 s y 4 s. Con 1 no hay reintento.
Guardar log de envíos	Guarda cada envío (payload, código y estado) en el registro. Sin él, no hay nada que reenviar.

Eventos activos

Una casilla por evento, con el hook de PrestaShop que lo dispara. Solo se envían los marcados.

Webhook entrante

Muestra la URL a la que n8n debe llamar, el secreto con el que se firman las peticiones (solo lo ve un SuperAdmin, con los botones Mostrar y Copiar) y la lista de acciones disponibles. Regenerar secreto crea uno nuevo: a partir de ese momento tus workflows tienen que firmar con él o la tienda los rechaza.

Test de conexión

Enviar webhook de prueba envía a tu URL un evento test y muestra el código HTTP que responde n8n. Lo correcto es un 200. Guarda la configuración antes de probar: la prueba usa la URL guardada.

Eventos que envía

Evento	Hook de PrestaShop	Qué lleva
order_created	actionValidateOrder	Pedido (id, referencia, estado, totales, envío, moneda, método de pago, fecha y líneas de producto), cliente y dirección de entrega.
order_status_changed	actionOrderStatusUpdate	Pedido con su estado nuevo, total y fecha, y el cliente.
customer_created	actionCustomerAccountAdd	Cliente: id, email, nombre, apellidos, tratamiento, fecha de nacimiento, newsletter, fecha de alta y grupos.
customer_updated	actionObjectCustomerUpdateAfter	Los mismos datos de cliente, ya actualizados.
product_add	actionObjectProductAddAfter	Producto: id, nombre en el idioma por defecto, referencia, precio, activo, cantidad disponible, categorías y fechas.
product_update	actionObjectProductUpdateAfter	Los mismos datos de producto, ya actualizados.
stock_update	actionUpdateQuantity	id_product, id_product_attribute, cantidad nueva, diferencia y, si viene de un pedido, su id.
cart_updated	actionCartSave	Carrito (id, total, productos) y cliente. Solo carritos de clientes identificados.

El evento de carrito se envía cuando PrestaShop ya ha asignado el carrito a la visita. Si todavía no lo ha hecho, se envía al final de esa misma petición. Si no se puede construir, la página sigue igual y el error queda en el registro.

Formato del envío

Cada evento es un POST con cuerpo JSON a la URL configurada:

{
  "event": "order_created",
  "source": "prestashop",
  "shop": "Nombre de tu tienda",
  "timestamp": "2026-09-29T10:15:00+02:00",
  "data": { "order": { … }, "customer": { … }, "shipping_address": { … } }
}

Cabeceras de cada envío:

Cabecera	Valor
Content-Type	application/json
X-Zeyvro-Event	El nombre del evento, por ejemplo order_created.
X-Zeyvro-Signature	HMAC-SHA256 del cuerpo exacto con tu secreto, en hexadecimal.
X-Webhook-Token	Tu token estático, solo si lo has rellenado.

Cada intento espera como máximo 3 s para conectar y 8 s en total. Un envío se da por bueno si n8n responde con un código 2xx.

Comprobar en n8n que el envío es tuyo

Tienes dos formas, y puedes usar las dos a la vez:

• Token estático (la más sencilla). Rellena Token estático en el módulo. En el nodo Webhook de n8n, elige la autenticación Header auth y crea la credencial con el nombre X-Webhook-Token y ese mismo valor. Las peticiones sin el token se rechazan antes de llegar a tu workflow.
• Firma HMAC. Calcula en n8n el HMAC-SHA256 del cuerpo recibido, tal cual llega, con el secreto que ves en Webhook entrante, y compáralo con X-Zeyvro-Signature. Tiene que ser el cuerpo exacto: activa la opción Raw Body del nodo Webhook, porque si lo vuelves a convertir a JSON antes de firmarlo, la firma no coincide.

Webhook entrante: de n8n a la tienda

La URL la copias del panel Webhook entrante del módulo. n8n la llama con un nodo HTTP Request:

1. Método POST y cuerpo JSON con action y data.
2. Cabecera X-Zeyvro-Signature con el HMAC-SHA256 en hexadecimal de ese cuerpo exacto, firmado con tu secreto.
3. Envía como cuerpo el mismo texto que has firmado.

{ "action": "update_stock", "data": { "id_product": 12, "id_product_attribute": 0, "quantity": 30 } }

Acción	Campos de data	Respuesta en result
update_stock	id_product (obligatorio), id_product_attribute (0 = producto sin combinación), quantity	updated, id_product, quantity
update_order_status	id_order y id_order_state (obligatorios)	updated, id_order, new_status. Queda en el historial del pedido.
create_customer	email (obligatorio), first_name, last_name	created, id_customer, email. El cliente se crea activo, con una contraseña aleatoria.
get_order	id_order (obligatorio)	id, reference, total, status, date

Para probar la conexión sin firmar nada: una petición GET a la URL con ?action=ping devuelve el estado y la versión del módulo.

Respuestas:

• 200: {"status":"ok","result":{…}}.
• 400: cuerpo vacío o sin action.
• 401: la firma no coincide. La tienda lo apunta en el registro de PrestaShop con la IP.
• 405: la petición no es POST (salvo el ping).
• 500: la acción falló, por ejemplo un pedido que no existe, un email ya registrado o un nombre no válido. El cuerpo lleva {"error":"…","status":"error"} con el motivo.

Registro de envíos

Menú Zeyvro → n8n Connector, o Ver logs desde la configuración.

• Webhooks salientes: evento, código HTTP, intentos, estado, error y fecha, de 30 en 30. Los envíos fallidos tienen el botón Reenviar, que vuelve a enviar los mismos datos a la misma URL.
• Webhooks entrantes: las 20 últimas peticiones de n8n, con su acción, su estado (recibido, procesado o error) y el resultado.

El registro de salida solo se escribe con Guardar log de envíos activado, que viene activado al instalar.

Cómo funciona por dentro

El módulo escucha los 8 hooks de la tabla de eventos y displayBackOfficeHeader, que carga sus estilos solo en sus páginas. Los datos viven en dos tablas propias: zeyvro_n8n_log (envíos) y zeyvro_n8n_incoming (peticiones de n8n). La configuración son 14 claves ZN8N_*.

Cada evento se envía en el momento en que ocurre, dentro de la misma petición: el del pedido, al confirmarlo. Si n8n no responde, la tienda espera como máximo 8 s por intento (3 s para conectar) y sigue; con más de un intento, entre uno y otro espera 1 s, 2 s y 4 s. El evento de carrito es la excepción: si el carrito aún no está listo, se envía al final de la petición.

Actualización, desinstalación y soporte

• Para actualizar, sube el ZIP nuevo desde Módulos → Subir un módulo, sin desinstalar. La configuración, el secreto y el registro se conservan.
• Al desinstalar, el módulo quita sus hooks y su pestaña del menú, pero conserva las dos tablas del registro y las 14 claves de configuración, por si lo vuelves a instalar.
• Soporte técnico por correo: hola@zeyvro.com.

Descargar la guía en PDF

Solución de problemas

La prueba no devuelve 200

Revisa que la URL sea la Production URL del nodo Webhook, no la Test URL (esa solo escucha 120 s después de pulsar Listen for test event), que el workflow esté publicado en n8n y que el nodo acepte POST. Si ves 0 como código, la tienda no ha llegado a conectar: el error de al lado dice por qué (DNS, certificado o tiempo de espera). Guarda la configuración antes de volver a probar.

n8n rechaza los envíos por autenticación

Si usas el token estático, el valor del módulo y el de la autenticación por cabecera de n8n tienen que ser idénticos, y el nombre de la cabecera, X-Webhook-Token. Si compruebas la firma, fírmala sobre el cuerpo exacto que llega, sin volver a convertirlo a JSON.

El webhook entrante responde 401

La firma no coincide. Comprueba que firmas con el secreto actual (si lo has regenerado, el anterior ya no vale), que el resultado va en hexadecimal y que el cuerpo que envías es exactamente el texto que has firmado.

El webhook entrante responde 500

La tienda ha recibido la petición, pero la acción no se ha podido hacer. El motivo viene en el campo error de la respuesta y en la columna Resultado de los webhooks entrantes: falta un campo obligatorio, el pedido no existe, el email ya tiene cuenta, el nombre no pasa la validación de PrestaShop o la acción no existe.

No llega un evento

Mira, por este orden: que el módulo esté activado, que la URL esté guardada, que ese evento esté marcado en Eventos activos y, en el registro de envíos, si salió y con qué código. El carrito solo se envía para clientes identificados.

PrestaShop 9.1 dice «no se puede actualizar ahora mismo» al subir el ZIP

Pasaba al actualizar desde la 1.3.5 o anteriores: el núcleo de 9.1 veía como duplicados los scripts de actualización que el módulo ya había ejecutado. Corregido en la 1.3.9. En 8.x y 9.0 no ocurre.

Historial de versiones

• 1.3.9 · 2026-09-27 — Corrige el aviso «no se puede actualizar» de PrestaShop 9.1 al actualizar desde la 1.3.5 o anteriores. Compatibilidad anunciada: de PrestaShop 8.0.0 a 9.1.3.
• 1.3.8 · 2026-09-26 — Webhook entrante: cualquier error interno responde 500 y deja la petición marcada como error. update_order_status y create_customer solo responden éxito si de verdad se guarda. El nombre y los apellidos se validan como en PrestaShop. La prueba de conexión muestra el resultado del envío que acaba de hacer.
• 1.3.7 · 2026-09-23 — La página siguiente al primer «añadir al carrito» ya no falla con el evento de carrito activo.
• 1.3.6 · 2026-09-12 — Primer arreglo del aviso de actualización de PrestaShop 9.1.

Preguntas frecuentes