Cómo conectar Cisco Finesse a n8n mediante Webhooks

El problema con la telemetría nativa de Cisco

Cisco Finesse es el agente desktop de UCCE/UCCX. Genera eventos ricos en tiempo real — cambios de estado de agente, inicio y fin de llamada, transferencias, eventos de outbound — pero acceder a ellos desde fuera del ecosistema Cisco requiere trabajo. La alternativa habitual (CUIC con consultas a Informix) es reactiva: requiere polling, los datos llegan con retraso y la base de datos no está pensada para procesos en tiempo real.

Los Finesse Gadgets (las extensiones embebidas en el portal del agente) tampoco resuelven el problema: están atados al navegador del agente y solo se ejecutan cuando ese agente está logado. Para cualquier flujo de orquestación serio — abrir tickets en ServiceNow al detectar un fallo, alertar en Teams cuando una cola supera un umbral, autorremediar caídas de gateway — necesitas algo distinto.

Los Webhooks HTTP de Finesse son la vía correcta. Empujan los eventos hacia un endpoint externo en tiempo real y permiten desacoplar el ecosistema Cisco del sistema de orquestación. En este tutorial montamos un receptor en n8n que procesa cada evento Finesse y lanza acciones según el tipo.

Prerequisitos

• Cisco Finesse 12.5 o superior con acceso de administrador
• Servidor n8n self-hosted (Docker recomendado) accesible desde la red de Finesse
• n8n expuesto por HTTPS con certificado válido — Finesse rechaza HTTP plano y autofirmados sin importar al trust store
• Credenciales de un agente de prueba en Finesse para validar el flujo

Paso 1: Crear el Webhook receptor en n8n

Crea un nuevo workflow en n8n y añade un nodo Webhook como trigger. Configúralo así:

// Configuración del nodo Webhook
HTTP Method:    POST
Path:           /finesse-events
Response Mode:  Immediately
Response Code:  200
Authentication: Header Auth
  Header Name:  X-Finesse-Secret
  Header Value: "un_secreto_largo_aqui"

Anota la Production URL generada — tendrá la forma:

https://n8n.tudominio.com/webhook/finesse-events

Paso 2: Suscribir el destino en Finesse

Finesse expone una API REST para gestionar suscripciones a eventos. Para registrar nuestro webhook como destino, usamos curl contra el endpoint de Notifications:

# Variables — sustituye con tus valores
FINESSE_HOST=finesse-prod.empresa.local
FINESSE_USER=administrator
FINESSE_PASS=tu_password
N8N_URL=https://n8n.tudominio.com/webhook/finesse-events

# Suscribir destino para todos los eventos de Dialog
curl -k -u $FINESSE_USER:$FINESSE_PASS \
  -X POST \
  -H "Content-Type: application/xml" \
  "https://$FINESSE_HOST:8445/finesse/api/Subscriptions" \
  -d '<Subscription>
    <name>n8n-orchestrator</name>
    <targetUri>'$N8N_URL'</targetUri>
    <eventType>DIALOG</eventType>
    <customHeaders>
      <header name="X-Finesse-Secret">un_secreto_largo_aqui</header>
    </customHeaders>
  </Subscription>'

Si todo está correcto, Finesse devuelve 201 Created con el ID de la suscripción. A partir de ese momento, cada cambio en una llamada se POSTea a tu webhook.

Paso 3: Parsear el XML en n8n

Finesse envía los eventos en XML. Añade un nodo XML después del Webhook para convertirlo a JSON manejable:

Mode:          XML to JSON
Property Name: body
Options:
  explicitArray:  false
  ignoreAttrs:    false

El JSON resultante tendrá una estructura como esta:

{
  "Update": {
    "event": "PUT",
    "data": {
      "dialog": {
        "id": "7000123",
        "state": "ACTIVE",
        "fromAddress": "+34912345678",
        "toAddress": "4001",
        "participants": {
          "participant": {
            "agentId": "agent007",
            "state": "TALKING",
            "stateChangeTime": "2026-05-05T10:32:14Z"
          }
        }
      }
    }
  }
}

Paso 4: Filtrar eventos relevantes

No todos los eventos requieren acción. Añade un nodo IF para filtrar solo los críticos. Estos son los patrones más útiles en producción:

• Llamadas perdidas: dialog.state == "FAILED" + fromAddress empieza por número externo
• Esperas largas: participant.state == "HOLD" + duración mayor a un umbral (calculada con $now - stateChangeTime)
• Caídas de agente: agentId.state == "NOT_READY" con reasonCode que indique fallo técnico
• Saturación de cola: agregando eventos por queueId en una ventana temporal

Paso 5: Disparar la acción

Con el evento ya parseado y filtrado, las acciones posibles son ilimitadas. En el caso de uso real que opera en producción para autorremediación de gateways UCCE, el flujo es:

1. Detectar evento de fallo de gateway desde Finesse
2. Enriquecer con datos contextuales (qué llamadas activas hay, qué agentes están afectados)
3. Crear ticket P1 en ServiceNow vía API REST
4. Notificar al canal de operaciones en Teams con el ID del ticket
5. Disparar workflow de remediación si la severidad lo permite

Lecciones aprendidas en producción

Tras 18 meses de operación real, estos son los aprendizajes que destilan la experiencia:

Idempotencia desde el día uno

Finesse puede reenviar el mismo evento si su servidor pierde el ACK por timeout. Si tu workflow crea tickets, asegúrate de incluir el dialog.id como clave única en ServiceNow para evitar duplicados. n8n permite hacer esto fácilmente con un nodo de búsqueda previa antes del nodo de creación.

Rate limiting interno

En picos de carga, Finesse puede enviar cientos de eventos por segundo. Si tu workflow encadena 5 nodos HTTP a sistemas externos, puedes saturar tanto n8n como las APIs destino. La solución: usar el patrón queue/worker con Redis, donde el webhook solo encola y un worker dedicado procesa con paralelismo controlado.

Trazabilidad sin compromiso

Cada evento debe quedar registrado, incluso los descartados por filtros. En entornos auditados (banca, telco con SLA), si no puedes demostrar qué eventos llegaron y qué decidiste hacer con ellos, el compliance no aprueba. Un nodo Postgres al inicio del workflow que guarda el evento crudo con timestamp soluciona esto.

Próximos pasos

Una vez tienes el webhook recibiendo eventos, las extensiones naturales son:

• Añadir un dashboard de eventos en tiempo real con Grafana + Loki
• Implementar correlación de eventos (un fallo de gateway suele preceder a varios fallos de llamada — agruparlos en un solo incident)
• Conectar con un LLM para clasificación automática de la severidad basándose en el patrón de eventos