Webhooks

Los webhooks son la forma estándar de que SIVO te envíe eventos en tiempo real: nuevas llamadas, transcripciones, agentes que cambian de estado, etc. Tu endpoint los recibe por HTTP POST y los procesa como quieras.

Eventos disponibles

Evento	Cuándo se dispara
call.created	Nueva llamada (entrante o saliente).
call.answered	Agente acepta.
call.transferred	Transferencia (ciega, atendida o 3-way).
call.ended	Cuelgue. Trae el CDR completo.
call.recorded	Grabación disponible con URL pre-firmada.
transcript.segment	Segmento de transcripción en vivo.
transcript.completed	Transcripción final consolidada.
queue.entered	Llamada entra en cola ACD.
queue.abandoned	Caller cuelga antes de ser atendido.
agent.status_changed	Available / On Call / On Break / Logged Out.
agent.paused	Pausa con motivo.
ivr.completed	Flujo IVR finalizado con variables capturadas.
ai_agent.completed	Conversación IA terminada con resumen.

Configuración

1. Settings → Webhooks → + Nuevo endpoint.
2. Rellena:
   • URL: tu endpoint HTTPS (HTTP plano no aceptado).
   • Eventos suscritos: marca solo los que te interesan.
   • Secret HMAC: SIVO lo genera o lo pones tú.
3. Guarda. SIVO envía un evento webhook.test automáticamente para verificar conectividad.

Puedes tener varios endpoints por tenant — uno para tu CRM, otro para tu BI, otro para Slack, etc.

Estructura de cada evento

{
  "id": "evt_01H8XYZ...",
  "type": "call.ended",
  "createdAt": "2026-05-20T10:23:45.123Z",
  "tenantId": "uuid-tenant",
  "data": {
    "callId": "uuid-call",
    "direction": "inbound",
    "from": "+34611222333",
    "to": "+34911234567",
    "duration_sec": 184,
    "agentId": "uuid-agent",
    "queueId": "uuid-queue",
    "mosScore": 4.3,
    "hangupCause": "NORMAL_CLEARING"
  }
}

Headers que SIVO envía:

Header	Valor	Para qué
X-Sivo-Event-Id	evt_01H8XYZ...	Idempotencia. Si recibes el mismo ID dos veces, descarta.
X-Sivo-Event-Type	call.ended	Para enrutar rápido sin parsear JSON.
X-Sivo-Signature	sha256=<hex>	Firma HMAC del body con tu secret.
Content-Type	application/json

Verificación de la firma

Cada request lleva una firma HMAC SHA-256 calculada sobre el body crudo con tu secret. Cómo verificarla en Node.js:

const crypto = require('crypto');

app.post('/webhooks/sivo', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-sivo-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('invalid signature');
  }

  const event = JSON.parse(req.body.toString());
  // Procesa el evento...
  res.status(200).send('ok');
});

Reintentos con backoff exponencial

Si tu endpoint devuelve un status fuera del rango 2xx, SIVO reintenta hasta 6 veces:

Intento	Espera tras el anterior
1	inmediato
2	5 segundos
3	30 segundos
4	2 minutos
5	10 minutos
6	1 hora
(después)	a la dead-letter queue

Tras el sexto fallo, el evento pasa a la DLQ (Dead Letter Queue) consultable desde el dashboard. Puedes:

• Reintentar manualmente desde el panel.
• Descargar el evento como JSON para inspección.
• Borrar si ya no es relevante.

Retención de la DLQ: 30 días.

Idempotencia

Asume que podrías recibir el mismo evento más de una vez (por timeout en tu lado, por ejemplo). Usa X-Sivo-Event-Id como clave de idempotencia. SIVO nunca cambia el ID en un reintento.

Tester integrado

En Settings → Webhooks → tu endpoint → Test, puedes:

• Disparar un evento sintético del tipo que elijas.
• Ver los últimos 100 envíos con status, latencia y body.
• Reenviar manualmente un evento fallido.

Limitaciones

• Body máximo: 256 KB.
• Timeout: 10 segundos. Si tu endpoint tarda más, cuenta como fallo. Mejor encolar internamente y responder 200 inmediato.
• HTTPS obligatorio.
• Sin redirecciones — SIVO no sigue 3xx.

Buenas prácticas

1. Devuelve 200 lo antes posible y procesa async en una cola interna.
2. Verifica la firma siempre — no confíes en headers.
3. Loga X-Sivo-Event-Id para correlacionar con SIVO si hay incidencias.
4. No proceses eventos por orden de llegada — los reintentos pueden alterar el orden. Usa createdAt o secuencias por recurso.
5. Reusa conexiones — establecer TLS por cada request añade latencia significativa.