Webhooks salientes en tiempo real y verificación de firma de seguridad HMAC-SHA256

Los Webhooks salientes de Waclis Inbox notifican en tiempo real a tus sistemas externos cada vez que ocurre un evento operativo en tu cuenta. Mediante peticiones HTTP POST en formato JSON firmadas con HMAC-SHA256, puedes sincronizar conversaciones, mensajes, contactos y movimientos de Kanban con tu ERP, CRM o automatizador sin consultar la API periódicamente.

Qué puedes hacer

Registrar múltiples endpoints HTTPS en Ajustes > Integraciones > Webhooks > Configurar > + Añadir nuevo webhook.
Asignar Nombre y Secreto HMAC a cada suscripción para identificar el destino y firmar los envíos.
Suscribirte a 13 eventos granulares de conversaciones, mensajes, contactos, widget web, escritura y tarjetas Kanban.
Verificar la autenticidad del payload validando la cabecera HTTP X-Waclis-Signature generada con HMAC-SHA256.
Editar o eliminar webhooks en cualquier momento sin afectar otras integraciones.

Cuándo conviene usarla

Sincronización con sistemas externos: Para reflejar al instante en tu ERP o base de datos cada contacto creado o conversación resuelta.
Orquestación de flujos (n8n, Make, Zapier): Para disparar procesos automáticos apenas entra un mensaje (message_created) o cambia una oportunidad (kanban_item_updated).
Auditoría y respaldo en vivo: Cuando requieres archivar eventos de mensajería en tiempo real en un repositorio propio.
Alertas operativas: Para avisar a un sistema externo cuando un chat cambia de estado (conversation_status_changed).

Disponibilidad por plan

Plan Estándar: Incluye gestión completa de Webhooks, los 13 eventos y firma HMAC-SHA256.
Plan Premium: Permite combinar Webhooks con bots externos y reglas avanzadas de automatización.
Plan Evolución: Suma arquitecturas corporativas combinando Webhooks con Servidores MCP, SLA y políticas avanzadas.

Requisitos previos

Rol de Administrador en Waclis Inbox.
Una URL del Webhook pública con protocolo HTTPS que reciba POST JSON y responda HTTP 2xx en menos de 5 segundos.
Una clave alfanumérica segura para el campo Secreto HMAC si validarás firmas criptográficas.

Cómo funciona en Waclis Inbox paso a paso

En el menú lateral izquierdo, ve a Ajustes > Integraciones.
En la tarjeta Webhooks, haz clic en Configurar.
Pulsa + Añadir nuevo webhook arriba a la derecha.
Completa los campos del modal:

URL del Webhook: Dirección HTTPS de tu servidor receptor (https://api.tuempresa.com/webhooks/inbox).
Nombre: Alias descriptivo de la integración (Sincronizador ERP).
Secreto HMAC: Clave privada con la que Waclis Inbox firmará cada petición usando HMAC-SHA256.

Marca las casillas de los eventos deseados entre los 13 eventos suscribibles.
Haz clic en Guardar para activar el envío en tiempo real.
En tu servidor receptor, lee la cabecera X-Waclis-Signature, calcula el digest HMAC-SHA256 del raw body con tu Secreto HMAC y compáralo en tiempo constante antes de procesar el JSON.

Opciones y configuraciones disponibles

Tabla de los 13 eventos suscribibles y parámetros en Ajustes > Integraciones > Webhooks:

Evento / Parámetro	Identificador técnico	Cuándo se dispara / Función
Conversación creada	`conversation_created`	Al abrirse un nuevo hilo en cualquier bandeja.
Estado cambiado	`conversation_status_changed`	Al cambiar el chat entre `open`, `resolved`, `pending` o `snoozed`.
Conversación actualizada	`conversation_updated`	Al cambiar agente, equipo, prioridad, etiquetas o atributos.
Mensaje creado / actualizado	`message_created` / `message_updated`	Al enviarse o recibirse un mensaje o nota privada, o al actualizarse.
Widget web activado	`webwidget_triggered`	Cuando un visitante abre el chat web en tu sitio.
Contacto creado / actualizado	`contact_created` / `contact_updated`	Al crearse una ficha nueva o modificarse sus atributos.
Escritura activada / desactivada	`conversation_typing_on` / `conversation_typing_off`	Cuando alguien comienza o deja de escribir en el hilo.
Kanban creado / actualizado / eliminado	`kanban_item_created` / `kanban_item_updated` / `kanban_item_deleted`	Al crear, mover de etapa, editar o borrar una tarjeta Kanban.
Secreto HMAC (`X-Waclis-Signature`)	Campo `Secreto HMAC`	Clave para firmar el cuerpo JSON con `HMAC-SHA256`.

Alternativas y cuándo elegir cada una

Mecanismo	Dirección del flujo	Cuándo elegirlo
Webhooks salientes	De Waclis Inbox a tu servidor (`Push`).	Para reaccionar al instante ante mensajes, estados o cambios en Kanban.
API REST Universal	De tu servidor a Waclis Inbox (`Pull` / acción).	Para buscar contactos, crear tareas o enviar mensajes activos.
Aplicaciones del panel	Incrustación visual.	Para mostrar un sistema externo dentro de la pantalla del agente.

Cómo se combina con otras funciones

Reglas de automatización: Puedes usar la acción Enviar un evento de webhook en Ajustes > Automatización para notificar una URL solo cuando se cumplan condiciones específicas.
Tableros Kanban: Escuchar kanban_item_updated permite registrar en tu ERP cada oportunidad ganada.
API REST: Recibes message_created por Webhook, evalúas la lógica en tu backend y respondes llamando a la API REST.

Relación con otros productos Waclis

En Waclis Inbox (Nativo): Emite en vivo los eventos conversacionales y de Kanban propios de Inbox.
Con el ecosistema Waclis (Waclis Connect, WaclisPOS, Waclis Factur, WaclisCAL y Waclis Reach): Waclis Connect gestiona de forma nativa la identidad (OIDC), las sesiones y el selector de aplicaciones (Universal App Switcher), sin compartir bases de datos entre productos. Cuando desees conectar flujos externos o coordinar eventos conversacionales (como message_created o kanban_item_updated) con sistemas propios o herramientas como Waclis Reach, puedes utilizar Webhooks salientes.
Con panel.waclis.com: Las suscripciones y planes de la organización se administran en panel.waclis.com.

Buenas prácticas

Importante: Valida X-Waclis-Signature sobre el cuerpo crudo (raw body): Calcula el HMAC-SHA256 con los bytes exactos recibidos antes de parsear el JSON y compáralo con timingSafeEqual para evitar ataques de falsificación.

Consejo: Responde HTTP 200 OK rápido y procesa en cola: Devuelve 200 OK de inmediato al recibir el webhook y ejecuta las tareas pesadas de forma asíncrona.

Errores frecuentes y solución de problemas

Síntoma	Causa raíz	Solución
Falla la verificación HMAC	Se calcula el hash sobre el JSON re-serializado en vez del raw body.	Usa el buffer crudo de la petición HTTP antes del parseo JSON.
Exceso de tráfico en tu servidor	Suscribiste eventos de alta frecuencia como `conversation_typing_on`.	Edita el webhook y marca únicamente los eventos necesarios.
No llegan eventos al endpoint	La URL usa HTTP sin SSL o bloquea peticiones por firewall.	Expón una URL `https://` pública con certificado válido.
Eventos procesados por duplicado	Tu servidor tardó en responder o escuchas `conversation_updated` y `conversation_status_changed` juntos.	Verifica el ID del evento para aplicar idempotencia.

Preguntas frecuentes

¿Qué diferencia hay entre `conversation_status_changed` y `conversation_updated`?

conversation_status_changed se emite solo cuando cambia el estado (open, resolved, pending, snoozed), mientras que conversation_updated cubre cambios de agente, equipo, etiquetas, prioridad o atributos.

¿El evento `message_created` incluye las notas privadas de los agentes?

Sí. En el JSON de message_created, la propiedad private: true identifica una nota interna y private: false un mensaje público.

¿Puedo registrar varios Webhooks en una misma cuenta?

Sí. En Ajustes > Integraciones > Webhooks > Configurar puedes registrar múltiples endpoints independientes con distintos eventos y secretos.

¿Qué algoritmo usa la cabecera `X-Waclis-Signature`?

Usa HMAC-SHA256 en formato hexadecimal calculado con tu Secreto HMAC sobre el cuerpo JSON crudo.

¿Necesitas más ayuda?

Si este artículo no resolvió tu consulta, nuestro equipo puede ayudarte personalmente.

Soporte por WhatsApp