Diagnóstico: Los eventos de conversaciones no se reflejan en el webhook, CRM externo o Aplicación del Panel

• Categoría: Solución de problemas
• Disponibilidad: Incluido en todos los planes (Estándar, Premium y Evolución)
• Tiempo estimado de resolución: 5 a 8 minutos
• Rol necesario: Administrador / Desarrollador de integración

Cuando conectas Waclis Inbox con un CRM externo, un motor de automatización (como n8n, Make o tu propio backend) mediante Webhooks, o cuando incrustas una herramienta interna mediante Aplicaciones del Panel, cualquier desajuste en los eventos suscriptos, la validación criptográfica HMAC-SHA256, los tiempos de respuesta HTTP o las cabeceras de seguridad del iframe interrumpirá la sincronización de datos. En esta guía técnica aprenderás a diagnosticar y reparar paso a paso cada punto de integración.

Cuadro de diagnóstico rápido (30 segundos)

Antes de comenzar (Requisitos previos verificables)

• Rol de Administrador: Solo los administradores pueden acceder a Ajustes → Integraciones → Webhooks y a Ajustes → Integraciones → Aplicaciones del Panel.
• Acceso a los registros (logs) de tu servidor receptor: Ten abierta la consola de tu aplicación externa, pasarela de API o flujo de automatización para observar el código de estado HTTP y las cabeceras entrantes.

Árbol de diagnóstico y solución paso a paso

Paso 1: Verificar la URL y las 8 casillas de eventos en Ajustes → Integraciones → Webhooks

Si tu CRM o sistema externo no recibe notificaciones cuando entra un mensaje o cambia un contacto, revisa primero la suscripción del webhook:

1. En Waclis Inbox, ve a Ajustes (icono de engranaje) → Integraciones y haz clic en Configurar dentro de la tarjeta Webhooks.
2. Localiza el endpoint afectado en la lista y haz clic en el botón de lápiz (Editar) (o pulsa Añadir nuevo webhook si aún no lo registraste).
3. Comprueba la URL del Webhook:

• Debe ser una dirección pública accesible desde internet con protocolo seguro https:// (nunca http://localhost, 127.0.0.1 ni una IP de red local interna).

1. Revisa las 8 casillas de Eventos disponibles y asegúrate de marcar exactamente los disparadores que tu sistema necesita escuchar:

• Conversación creada: Se dispara cuando se abre un nuevo hilo de conversación.
• Estado de conversación cambiado: Se dispara cuando el chat pasa entre Abierta, Pendiente, Pospuesta o Resuelta.
• Conversación actualizada: Se dispara cuando cambia el agente asignado, el equipo, la prioridad, las etiquetas o los atributos personalizados de la conversación (imprescindible para sincronizar cambios de etapa o asignación con un CRM).
• Mensaje creado: Se dispara con cada mensaje entrante del cliente, respuesta saliente del agente o nota privada.
• Mensaje actualizado (message-updated): Se dispara cuando cambia el estado de entrega/lectura o se edita/elimina un mensaje.
• Contacto creado y Contacto actualizado: Sincronizan altas y modificaciones de fichas en el directorio de Contactos.
• Widget web activado: Notifica cuando un visitante abre el chat en tu sitio web.

1. Guarda los cambios. Si utilizas un Canal API personalizado, recuerda que también puedes definir una URL de Webhook específica para esa bandeja dentro de Ajustes → Entradas → [Bandeja API] → Ajustes.

Paso 2: Diagnosticar fallos en la validación de firma HMAC-SHA256

Cada webhook enviado por Waclis Inbox incluye un Secreto HMAC para que tu servidor verifique que el paquete proviene legítimamente de tu cuenta y no fue alterado en tránsito.

1. En Ajustes → Integraciones → Webhooks (o en la pestaña Ajustes de un Canal API), copia el valor del Secreto del webhook (Secreto HMAC).
2. Error común de implementación: Muchos frameworks web (como Express en Node.js, FastAPI o PHP) convierten automáticamente el JSON entrante en un objeto y luego el desarrollador vuelve a ejecutar la re-serialización del cuerpo JSON para calcular el HMAC. Cualquier diferencia mínima de espacios o saltos de línea cambiará el hash resultante y hará que la validación falle.
3. Solución correcta: Calcula siempre el digest HMAC-SHA256 utilizando la clave secreta directamente sobre la cadena de bytes original (raw request body) tal como llegó por la red antes de parsear el JSON, y compáralo mediante una función de tiempo constante (comparación segura de firmas / comparación segura de firma) contra la firma recibida en la cabecera HTTP.

Paso 3: Asegurar respuestas HTTP 2xx rápidas para evitar cortes por Timeout

El despachador de webhooks de Waclis Inbox envía las peticiones en segundo plano esperando una confirmación rápida de recepción:

1. Si tu servidor receptor recibe el evento Mensaje creado y, antes de responder el HTTP, intenta consultar tres APIs externas, generar un PDF y escribir en una base de datos lenta tardando más de 10 a 15 segundos, la conexión se cortará por timeout.
2. Arquitectura recomendada: Apenas tu endpoint reciba el payload de Waclis Inbox y valide la firma HMAC-SHA256, responde inmediatamente con un código HTTP 200 OK (o 202 Accepted) en menos de 2 segundos y delega el procesamiento pesado a una cola asíncrona en tu servidor.
3. Verifica también que ningún firewall o proxy intermedio (como Cloudflare Bot Fight Mode o reglas WAF restrictivas) esté devolviendo un 403 Forbidden o un desafío CAPTCHA a las peticiones salientes de Waclis Inbox.

Paso 4: Diagnosticar Aplicaciones del Panel que no cargan o no reciben Contexto de la conversación

Las Aplicaciones del Panel permiten incrustar sistemas externos o pantallas de gestión como una pestaña más dentro de la conversación activa. Si la pestaña no muestra tu aplicación o no carga los datos del cliente:

1. Verificar protocolo HTTPS y cabeceras de iframe:

• Entra a Ajustes → Integraciones → Aplicaciones del Panel y revisa el campo Endpoint (URL). Como Waclis Inbox corre bajo https://inbox.waclis.com, el navegador bloqueará por Mixed Content cualquier URL que empiece con http://.
• Abre las herramientas de desarrollador del navegador (F12 → pestaña Consola / Red). Si ves el error Refused to display '...' in a frame because it set 'X-Frame-Options' to 'deny' (o 'sameorigin'), debes configurar tu servidor web externo para eliminar X-Frame-Options: DENY y enviar la cabecera estándar:

Content-Security-Policy: frame-ancestors 'self' https://inbox.waclis.com;

1. Escuchar correctamente el evento JSON Contexto de la conversación:

• Cuando el agente abre la pestaña de tu Aplicación del Panel, Waclis Inbox envía automáticamente al iframe mediante mensajería del navegador un paquete con los datos de la conversación activa (conversation), del cliente (contact) y del agente conectado (agente actual).
• En la página web incrustada, asegúrate de escuchar el mensaje de contexto enviado por la ventana principal al abrir la pestaña (consulta el ejemplo técnico completo en la guía de Aplicaciones del panel: incrustación de portales web en marcos contextuales del chat).

Tabla de referencia técnica para integradores

Prevención y cómo combinarlo con otras funciones de Waclis Inbox

1. Dispara Webhooks selectivos desde Reglas de Automatización: En lugar de suscribir un webhook global a todos los mensajes de la cuenta y filtrar el ruido en tu servidor, puedes ir a Ajustes → Automatización y crear una regla que, solo cuando se cumplan condiciones exactas (por ejemplo, Etiquetas → Igual a → venta-cerrada), ejecute la acción Enviar un evento de webhook hacia la URL específica de tu ERP.
2. Audita cambios inesperados en Registros de auditoría: Si un webhook o una regla dejó de funcionar repentinamente, un Administrador puede entrar a Ajustes → Registros de auditoría para verificar quién editó o eliminó un webhook, una regla o un canal, con fecha, hora y dirección IP.

Relación con el ecosistema Waclis

• WaclisCAL, Waclis Factur y Waclis Work como Aplicaciones del Panel: Dentro del ecosistema Waclis, puedes incrustar WaclisCAL (para ver turnos del contacto en la barra lateral), Waclis Factur (para consultar comprobantes fiscales emitidos sin cambiar de pestaña; recuerda que toda emisión electrónica ARCA/AFIP ocurre en Waclis Factur) o accesos a Waclis Work directamente mediante Aplicaciones del Panel.
• WaclisPOS y Waclis Reach: Pueden integrarse mediante la API REST y los Webhooks de Waclis Inbox si se configuran en tu cuenta utilizando tu Token de acceso.

Preguntas frecuentes (FAQ)

¿Dónde encuentro mi Token de acceso para que mi CRM consulte la API REST de Waclis Inbox?

No está en los ajustes generales de la cuenta, sino en tu perfil personal: haz clic en tu avatar en la esquina inferior izquierda → Ajustes del perfil, desplázate hasta el final de la página hasta la sección Token de acceso y haz clic en Copiar.

¿Por qué mi integración por API dejó de funcionar con error 401 Unauthorized si nadie tocó el código?

Esto ocurre cuando el usuario dueño del Token de acceso hizo clic en el botón Reiniciar dentro de Ajustes del perfil → Token de acceso, o cuando ese usuario fue eliminado de Ajustes → Agentes. Te recomendamos generar el token desde una cuenta de Administrador estable y actualizar la cabecera Token de acceso en tu sistema externo.

¿Las Notas privadas disparan el evento Mensaje creado en los Webhooks?

Sí. Cuando un agente escribe una Nota privada dentro de una conversación, se emite el evento Mensaje creado con la propiedad "private": true dentro del JSON. Tu sistema externo puede inspeccionar ese booleano para distinguir entre respuestas públicas al cliente ("private": false) y comentarios internos del equipo ("private": true).

Artículos relacionados

• Webhooks salientes en tiempo real y verificación de firma de seguridad HMAC-SHA256: API REST y Webhooks con firma HMAC: guía práctica de integración y eventos disponibles
• API REST de Cuenta y Client API: autenticación, tokens y endpoints principales: Creación y configuración de un Canal API para integraciones personalizadas
• Aplicaciones del panel: incrustación de portales web en iFrames contextuales del chat: Aplicaciones del Panel: cómo incrustar sistemas externos dentro de la conversación
• Cómo se integra Waclis Inbox con el ecosistema Waclis (Tienda Web, WaclisPOS, WaclisCAL, Waclis Factur, Waclis Reach, WaclisMAIL y Waclis Work): Cómo se integra Waclis Inbox con el ecosistema Waclis