Webhook

El objetivo principal es que puedas mantener tus propios sistemas actualizados con lo que ocurre en Moonflow.

Por ejemplo:

• Tu sistema tiene los datos de los clientes.
• Moonflow gestiona las cobranzas.
• A través del Webhook, tu sistema recibe actualizaciones sobre pagos, promesas, interacciones y comunicaciones.

De esta forma, Moonflow no reemplaza tu base de datos, sino que se conecta con ella para facilitar la gestión y mantener todo sincronizado.

Debes configurar una URL de tu sistema que esté preparada para recibir los eventos.

Esa URL debe estar siempre disponible, ya que Moonflow le enviará datos cada vez que ocurra una acción.

👉 Esto requiere asistencia de tu equipo técnico.

La URL debe poder recibir solicitudes HTTP POST y procesar datos en formato JSON.

Sí.

• Puedes usar solo Webhook si solo necesitas recibir información en tiempo real.
• Puedes usar solo API si querés enviar o consultar datos desde tu sistema.
• También puedes usar ambos al mismo tiempo, según tus necesidades.
• No son dependientes entre sí.

• Seguridad: Evitas que terceros envíen mensajes falsificados a tu sistema.
• Fiabilidad: Procesas solo información genuina proveniente de Moonflow.
• Automatización: Gestionas eventos de manera instantánea y segura.

• Automatización: actualiza automáticamente tu sistema en función de cambios en Moonflow.
• Velocidad: recibe eventos en tiempo real, sin demoras ni procesos manuales.
• Precisión: disminuye errores de actualización de datos.
• Flexibilidad: adapta las respuestas de tu sistema según los eventos recibidos.

• Moonflow envía automáticamente los datos a una URL que tú configures.
• Esa URL actúa como un "listener" o 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.).
• Tu sistema debe guardar, procesar o transformar esa información si luego quieres consultarla, visualizarla o exportarla.

1. Configura el Webhook en Moonflow: En Ajustes > Integraciones > Webhook > Agregas la URL de tu servidor.
2. Cuando ocurre una interacción de comunicación (ej: email abierto, mensaje de WhatsApp leído), Moonflow:
   • Envía automáticamente un JSON a esa URL.
   • El JSON incluye todos los datos del evento (tipo de canal, ID de cliente, fecha/hora, estado, etc.).

   Ejemplo básico del JSON que podrías recibir:

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

3. Tu servidor recibe y guarda esa información.
   Si quieres descargarla, deberás generar un archivo desde tu backend, con los datos que almacenaste.

💡 Recuerda que en la bandeja de Interacciones puedes descargar hasta 45 días de datos por vez (puedes filtrar las fechas que precises). Aprende más sobre este tema en los siguientes artículos: Interacciones y ¿Cómo descargar reportes?.

📌 Nota importante: Recibir y guardar interacciones vía Webhooks requiere conocimientos técnicos. Alternativamente, puedes usar herramientas como Zapier o Make, aunque con menos flexibilidad.

Paso 1: Recibir la información

Debes tener un servidor web (como si fuera una página especial) preparado para recibir esos mensajes. Cada vez que Moonflow envía información, tu servidor la guarda automáticamente.

¿Qué necesitas?

• Una URL configurada en Moonflow.
• Un programador o un sistema que pueda recibir y guardar esos datos.

Paso 2: Guardar los datos

Los datos que te manda Moonflow pueden guardarse en una base de datos o incluso en un archivo de texto simple, si no tienes algo más complejo. Por ejemplo, podrías guardar:

• Cliente: 12345
• Canal: WhatsApp
• Tipo de evento: mensaje leído
• Fecha y hora: 21/05/2025 10:34

Paso 3: Generar un archivo CSV

Una vez que tienes la información guardada, puedes:

• Filtrarla (por fecha, canal, tipo de mensaje).
• Armar una tabla con esos datos.
• Convertir esa tabla en un archivo CSV, que se abre fácilmente en Excel o Google Sheets.

💡 Un programador puede hacer que al entrar a una página específica (como "tusistema.com/reportes"), se descargue automáticamente ese archivo CSV.

Tu URL actúa como un listener (escuchador). Está en espera, y cada vez que ocurre un evento en Moonflow, se le envía un mensaje con los datos correspondientes.

Esto permite mantener tu sistema sincronizado con lo que ocurre en Moonflow, sin necesidad de hacer consultas manuales o programadas.

Cuando activas un Webhook en Moonflow, puedes recibir notificaciones en tu endpoint (URL configurada) cada vez que se registre uno de estos eventos:

• Creación de un pago.
• Actualización de un estado de orden de pago.
• Actualización de datos de clientes, entre otros.

Una vez configurado, Moonflow enviará a tu URL los eventos que se produzcan en tiempo real, por ejemplo:

• Eventos de pago: compromiso de pago, pago a verificar, pago no verificado, etc.
• Eventos de comunicación: email abierto, mensaje leído, rechazo, rebote, etc.
• Eventos de interacción: cuando el cliente responde a una comunicación o realiza una acción en un canal.

Tu sistema recibe toda esta información automáticamente y puede actualizar su base de datos o ejecutar acciones internas.

No. Si escribes una nota o comentario desde el módulo de Conversaciones, esa información no se envía por Webhook.

Por ejemplo, si marcas el resultado de una llamada (como pausar, reprogramar o seleccionar No quiere pagar) y agregas un comentario sobre la gestión, ese texto no se transmite por webhook.

💡 Los webhooks en Moonflow no incluyen notas internas ni comentarios escritos manualmente en la gestión de llamadas.

Para configurar tu Webhook en Moonflow, sigue estos pasos:

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

2. En el menú, selecciona Integraciones.

3. Accede a la pestaña Webhook.

Allí podrás:

• Editar 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).

Haz clic en Guardar para activar tu Webhook.

🔔 Recuerda: La URL debe ser pública y estar preparada para recibir solicitudes POST con formato JSON.

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, aplicando el algoritmo HMAC-SHA256 codificado en Base64.

Pasos para validar la autenticidad de los mensajes:

• Copia la llave de firma que ves en el apartado de Webhook de Moonflow.
• Guarda esta llave de firma en un lugar seguro en tu servidor.

En tu código que maneja los Webhooks:

• Usa la llave para generar tu propia firma sobre el cuerpo del mensaje recibido.
• 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.

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.