Este artículo técnico detalla el funcionamiento de los Eventos de Ciclo de Vida de Sesión y Webhooks en el ecosistema de Darwin. Estos eventos permiten a los desarrolladores integrar flujos externos, realizar análisis de datos en tiempo real y automatizar acciones basadas en el comportamiento de las sesiones.
1. Eventos de Ciclo de Vida de Sesión (Session Lifecycle)
Los eventos de sesión permiten rastrear el estado de una conversación desde su apertura hasta su cierre o transición.
session.opened: Se dispara en el momento exacto en que inicia una nueva sesión.session.closed: Se activa cuando una sesión finaliza (comúnmente por inactividad del usuario).session.closed.unforwarded: Específico para sesiones que cerraron sin haber sido transferidas a un agente humano o flujo externo.session.analyzed: Se dispara tras el procesamiento de IA, una vez que los campos inteligentes (smart fields) se calculan y el resumen de la conversación está disponible.session.stage.transitioned: Útil para pipelines de ventas o soporte; se activa cuando la sesión cambia de una etapa a otra.session.*: Comodín (Wildcard) para suscribirse a todos los eventos de ciclo de vida y transferencia simultáneamente.
Eventos de Transferencia (Session Transfer)
session.forwarded: Evento genérico de transferencia.session.forwarded.qualified: La sesión fue transferida por cumplir criterios de calificación específicos.session.forwarded.escalated: Indica que la sesión fue escalada (ej. de bot a supervisor).session.forwarded.recovered: La sesión se transfirió como parte de un flujo de recuperación.
2. Ejecución de Funciones (Function Execution)
Estos eventos permiten monitorear cuándo el motor de IA invoca herramientas o funciones externas.
function.call.<functionName>: Se activa cuando una función específica es ejecutada.function.call.*: Suscribe a todas las ejecuciones de funciones.function.*: Comodín para cualquier evento relacionado con funciones.
3. Estructura de la Carga Útil (Webhook Payload)
Todos los webhooks enviados por Darwin comparten una estructura base enriquecida con metadatos del agente y el evento.
Propiedades Comunes
Propiedad | Descripción |
| El tipo de evento (ej. |
| Fecha y hora en que ocurrió el evento. |
| Identificador único del agente relacionado. |
| Nombre del agente. |
| Objeto que contiene la información específica del evento. |
Detalles en Eventos de Sesión (data)
Dentro del objeto data, encontrarás información contextual profunda:
Identificadores:
conversationId,sessionId,channelId.Tiempos:
createdAt,closedAt,lastHumanActivityAt.IA & Análisis:
summary(resumen generado),smartFields(datos extraídos),summarizedAt.Transferencia:
forwardedToId,forwardType.
Detalles en Eventos de Función (data)
Contexto de Ejecución:
inputs(parámetros enviados),functionName,functionStatus.Trazabilidad:
functionCallId,conversationThreadId.App Metadata: Información sobre la aplicación que originó la llamada (si aplica).
4. Seguridad e Integridad (Payload Integrity)
Para garantizar que los eventos provienen de Darwin y no han sido alterados, cada solicitud incluye una firma criptográfica en el encabezado.
Mecanismo: HMAC-SHA256.
Header:
X-SIGNATURE.
Verificación en Node.js
Para validar el payload, computa el hash del cuerpo de la solicitud (raw body) usando tu secreto y compáralo con la firma recibida:
JavaScript
const crypto = require('crypto'); // 'request.body' debe ser el cuerpo crudo de la petición const payload = JSON.stringify(request.body); const secret = 'tu_secreto_de_app'; const receivedSignature = request.headers['x-signature']; const expectedSignature = crypto.createHmac('sha256', secret) .update(payload) .digest('hex'); if (receivedSignature !== expectedSignature) { throw new Error('Firma inválida: la petición no es auténtica.'); } // Proceder con el procesamiento del evento