¿Cómo configurar el webhook?

Un webhook es un canal de comunicación entre Moonflow y tu sistema, que envía automáticamente notificaciones en tiempo real a una URL que tú configures. Esta actúa como un receptor que recibe un POST en formato JSON cada vez que ocurre una interacción relevante (por ejemplo, un mensaje enviado, leído, rechazado, etc.).

A diferencia de la API, donde tú haces una consulta, con el webhook no es necesario hacer ninguna acción: Moonflow te envía automáticamente los datos cuando ocurre un evento.

¿Qué necesito para configurarlo?

1. Antes que nada, necesitarás un sistema que pueda recibir y guardar los datos que te enviemos. Es decir, debes tener un servidor web que esté preparado para recibir los eventos. Esa URL de tu sistema debe ser pública y tiene que poder recibir solicitudes HTTP POST y procesar datos en formato JSON.

2. Necesitarás asistencia de tu equipo técnico.

¿Qué información se envía?

📌 Importante: No se envían eventos de creación o actualización de clientes u órdenes de pago por webhook.

El webhook configurado notificará 2 tipos principales de interacción:

1. Registros de comunicación. Incluyen notificaciones sobre mensajes salientes enviados por distintos canales como WhatsApp, correo, SMS, etc.
También se envían actualizaciones sobre el estado de estas comunicaciones, tales como enviado, entregado, abierto, leído y fallido (rebote, rechazo, error de entrega).

2. Registros de eventos. Es decir, notificaciones sobre acciones específicas realizadas en relación con una orden de pago, como compromisos de pago, pagos a verificar, pagos verificados, pagos no verificados y anulaciones de pagos.

Cuando ocurre alguna de estas interacciones, Moonflow envía un JSON que incluye todos los datos del evento (tipo de canal, ID de cliente, fecha/hora, estado, etc.).
Por ejemplo:

{
  "event_type": "communication_read",
  "channel": "whatsapp",
  "customer_id": "12345",
  "timestamp": "2025-05-21T10:34:00Z",
  "message_id": "abc789"
}

Paso a paso: Configura tu webhook en Moonflow

1. Haz clic en el icono de engrane (⚙️) en la esquina superior derecha del dashboard.

2. En el menú, selecciona Integraciones.

3. Accede a la pestaña Webhook. Allí podrás:

Agregar la URL del webhook donde deseas recibir las notificaciones.

Ver la llave de firma del webhook para validar la autenticidad de los mensajes.

Probar la conexión enviando un JSON vacío para validar que la URL funcione correctamente (el cambio puede demorar hasta 15 minutos en aplicarse).

4. Haz clic en Guardar para activar tu Webhook.

Paso a paso: Valida la autenticidad de los mensajes enviados

Moonflow implementa un sistema de validación de firmas para garantizar que los mensajes que recibes provienen realmente de Moonflow y no de terceros. Cuando configures tu webhook, cada mensaje incluirá en su encabezado (header) un valor llamado moonflow-signature. Esta firma se genera usando tu llave de firma y el contenido completo del mensaje.

Paso a paso:

1. Haz clic en el icono de engrane (⚙️) en la esquina superior derecha del dashboard.

2. En el menú, selecciona Integraciones.

3. Accede a la pestaña Webhook.

4. Copia la llave de firma que ves en el apartado de webhook de Moonflow.

5. Guarda esta llave de firma en un lugar seguro en tu servidor.

6. En tu código que maneja el webhook, usa la llave para generar tu propia firma sobre el cuerpo del mensaje recibido.

7. Compara tu firma generada con el valor de moonflow-signature enviado por Moonflow.

Si coinciden, el mensaje es válido.
Si no, debes descartarlo.

🔔 Importante: Esta validación protege tus datos y asegura que solo proceses mensajes auténticos enviados por Moonflow.

Paso a paso: Configura el webhook en Meta Developers

Además de configurarlo en Moonflow, también debes registrar el webhook en tu cuenta de WhatsApp Business en Meta Developers:

1. Crea una aplicación en Meta Developers.

2. Agrega el producto WhatsApp.

3. Configura la URL del Webhook y el Token de Verificación.

4. Suscríbete a los siguientes eventos:

messages

message_template_status_update

business_status_update

messaging_handovers

flows

Recuerda que la URL del webhook debe ser accesible públicamente mediante HTTPS y tener un certificado SSL válido.