DataFirefly Webhooks — Guía completa

Introducción

DataFirefly Webhooks conecta tu tienda PrestaShop 8 y 9 con más de 5000 aplicaciones, en ambos sentidos. En saliente, tu tienda emite sus eventos (pedidos, clientes, stock…) hacia Zapier, Make, n8n o cualquier endpoint HTTP. En entrante, esas mismas herramientas pueden enviar datos a la tienda mediante una API segura.

El módulo se apoya en tres pilares: una cola asíncrona (ningún pedido se ralentiza), reintentos automáticos con backoff exponencial y una firma HMAC-SHA256 para garantizar la autenticidad de los mensajes.

Instalación

1. Descarga el archivo dfwebhooks.zip desde tu cuenta DataFirefly.
2. En el back office, ve a Módulos > Gestor de módulos > Subir un módulo y suelta el ZIP.
3. Haz clic en Instalar y luego en Configurar.
4. Llegas a la pantalla principal que muestra la URL del worker cron y la URL de la API entrante.

1. Programar el worker cron (flujo saliente)

Los webhooks salientes no se envían de inmediato: se ponen en cola y los entrega un worker que activas periódicamente. Copia la URL del cron que aparece en la pantalla de configuración y prográmala cada 1 a 5 minutos.

*/2 * * * * curl -s "https://tu-tienda.com/index.php?fc=module&module=dfwebhooks&controller=cron&token=TU_TOKEN" >/dev/null 2>&1

En cada pasada, el worker procesa hasta 50 entregas pendientes, aplica los reintentos necesarios y purga los registros antiguos según la retención configurada.

2. Crear un endpoint saliente

Un endpoint vincula un evento con una URL de destino. Desde la pantalla principal, haz clic en Añadir y completa:

• Nombre: una etiqueta interna (ej. «Nuevo pedido → Zapier»).
• Evento: el evento desencadenante (ver la lista más abajo).
• URL: pega la URL «Catch Hook» de Zapier o «Custom Webhook» de Make.
• Secreto de firma (opcional): si se indica, cada payload se firma con HMAC-SHA256.

Filtros condicionales

Puedes enviar un webhook solo cuando se cumplen ciertas condiciones. Las reglas están en JSON y se combinan con Y lógico. Operadores disponibles: eq, neq, gt, gte, lt, lte, in, contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Este ejemplo dispara el webhook solo para los pedidos cuyo total pagado es mayor o igual a 100.

Mapeo de campos

Por defecto se envía el payload completo. Para enviar solo ciertos campos con un formato preciso, define un mapeo: la clave es el nombre de salida, el valor es la ruta dentro del payload.

{"email":"customer.email","total":"order.total_paid"}

3. Eventos salientes disponibles

• order.created — se acaba de validar un pedido.
• order.status.updated — cambia el estado de un pedido.
• order.refunded — un pedido pasa al estado reembolsado.
• customer.created — se registra un nuevo cliente.
• address.created — se crea una nueva dirección.
• product.created — se añade un producto.
• product.updated — se modifica un producto.
• product.stock.low — el stock baja del umbral configurado.
• review.created — se aprueba una reseña (requiere un módulo de reseñas compatible).

4. API entrante (Zapier/Make/n8n → PrestaShop)

La API entrante permite que tus automatizaciones modifiquen la tienda. Está protegida por un token y, opcionalmente, por una firma HMAC.

Crear un token

En el panel Tokens entrantes, dale una etiqueta, elige los scopes permitidos (orders, products, customers) y, si lo deseas, un secreto de firma. El token generado se pega en tu herramienta.

Enviar una petición

Haz un POST a la URL de la API entrante. El token va en la cabecera X-DF-Token (o como parámetro ?token=). El cuerpo es un JSON con una action y un objeto data.

POST https://tu-tienda.com/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: TU_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Acciones entrantes disponibles

• order.status.update (scope orders) — cambia el estado de un pedido. Campos: id_order, id_order_state, send_email (opcional).
• order.get (scope orders) — recupera un pedido. Campo: id_order.
• product.stock.update (scope products) — fija el stock. Campos: id_product, quantity, id_product_attribute (opcional).
• product.upsert (scope products) — crea o actualiza un producto por su reference.
• customer.upsert (scope customers) — crea o actualiza un cliente por su email.
• customer.get (scope customers) — recupera un cliente por email o id_customer.

6. Verificar la firma HMAC

Si hay un secreto configurado en el endpoint (saliente) o en el token (entrante), el mensaje lleva una cabecera X-DF-Signature: sha256=.... Para verificarla en recepción, vuelve a calcular el HMAC del cuerpo bruto con tu secreto y compara en tiempo constante.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // firma válida
}

Calcula siempre el HMAC sobre el cuerpo bruto (no reserializado), de lo contrario la firma no coincidirá.

7. Registro de entregas y reenvío

El menú Webhooks Delivery Log lista cada intento con su estado:

• SENT — entregado con un código HTTP 2xx.
• PENDING — en cola, esperando la próxima pasada del worker.
• FAILED — fallo temporal, se programa un reintento.
• DEAD — fallo definitivo tras 6 intentos.

Los reintentos siguen un backoff exponencial: 1 minuto, 5 minutos, 30 minutos, 2 horas y luego 6 horas. Puedes forzar un nuevo envío en cualquier momento con el botón Replay, e inspeccionar el payload exacto desde la acción Ver.

8. Multitienda, RGPD y modo por lotes

Cada endpoint y cada token están asociados a una tienda concreta: los flujos de una tienda nunca se filtran a otra. La opción Anonimizar los datos personales enmascara correos, teléfonos y nombres antes del envío, para cumplir el RGPD cuando el destino no debe recibir datos identificativos. El modo por lotes agrupa los envíos para grandes volúmenes.

FAQ y resolución de problemas

No se envía ningún webhook. Comprueba que el worker cron está programado y que su URL (con el token correcto) responde. Revisa el registro: si las filas se quedan en PENDING, el cron no se está ejecutando.

El endpoint remoto devuelve un error 401/403. Tu herramienta puede esperar una verificación de firma: indica el mismo secreto en ambos lados, o quítalo durante las pruebas.

La API entrante devuelve «insufficient_scope». El token usado no tiene el scope requerido por la acción. Edita el token para marcar el scope correspondiente (orders, products o customers).

El botón de prueba muestra un fallo. El botón Test envía un payload de ejemplo de forma síncrona: un fallo suele indicar una URL inalcanzable o un certificado TLS inválido en el destino.