Webhooks e Integraciones

8.1 Que son los Webhooks

Los webhooks permiten que Voki envie notificaciones automaticas a sus sistemas externos cuando ocurren eventos especificos. Por ejemplo, puede recibir una notificacion cuando se completa una llamada para registrar la atencion en su CRM.

Disponibilidad: Planes Avanzado, Profesional y Enterprise.

8.2 Configurar un Webhook

1. Acceda a "Configuraciones" > "Webhooks" en el Panel del Gestor
2. Haga clic en "Nuevo Webhook"
3. Complete:
   • URL: el endpoint de su sistema que recibira las notificaciones (debe aceptar POST)
   • Eventos: seleccione cuales eventos desea recibir
   • Secret: clave secreta para validacion HMAC (generada automaticamente o definida por usted)
4. Haga clic en "Guardar"

8.3 Eventos Disponibles

Evento	Descripcion	Cuando se dispara
call.created	Llamada creada	El cliente entra en la cola
call.assigned	Llamada asignada	El agente acepta la llamada
call.started	Llamada iniciada	Conexion WebRTC establecida
call.completed	Llamada completada	La llamada finalizo normalmente
call.missed	Llamada perdida	El cliente salio de la cola sin atencion
customer.created	Cliente creado	Nuevo cliente registrado

8.4 Firma HMAC-SHA256

Cada notificacion enviada por Voki incluye una firma HMAC-SHA256 en el encabezado X-Voki-Signature. Utilice esta firma para validar que la solicitud realmente proviene de Voki:

# Ejemplo de validacion en Python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

// Ejemplo de validacion en Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

8.5 Formato del Payload

Cada notificacion se envia como una solicitud HTTP POST con el siguiente formato:

{
  "event": "call.completed",
  "timestamp": "2026-02-20T14:30:00Z",
  "data": {
    "id": "uuid-de-la-llamada",
    "status": "completed",
    "duration_seconds": 342,
    "department_id": "uuid-del-departamento",
    "attendant_id": "uuid-del-agente",
    "customer": {
      "name": "Nombre del Cliente",
      "email": "cliente@email.com"
    }
  }
}

Encabezados enviados:

Content-Type: application/json
X-Voki-Signature: sha256=abc123...
X-Voki-Event: call.completed
X-Voki-Delivery: uuid-del-delivery

8.6 Entregas y Reenvio

Cada intento de entrega de webhook queda registrado. En la pagina de detalles del webhook, puede:

• Visualizar el historial de entregas (deliveries)
• Ver el estado de cada entrega (exito, fallo, timeout)
• Reenviar una entrega que fallo

8.7 Probar un Webhook

Para verificar si su endpoint esta funcionando correctamente:

1. En la lista de webhooks, haga clic en "Probar" junto al webhook deseado
2. El sistema envia un payload de prueba al endpoint configurado
3. El resultado (exito o error) se muestra inmediatamente

---