Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta de Auralytik. Registra un endpoint, elige los eventos que te interesan, y enviaremos un payload JSON firmado a tu servidor cada vez que se dispare un evento.

Endpoints

Metodo	Ruta	Alcance	Descripcion
GET	/api/v1/webhooks	webhooks:manage	Listar todos los registros de webhooks
POST	/api/v1/webhooks	webhooks:manage	Crear un nuevo webhook (retorna secreto de firma)
PATCH	/api/v1/webhooks/{id}	webhooks:manage	Actualizar URL, eventos o estado activo
DELETE	/api/v1/webhooks/{id}	webhooks:manage	Eliminar / desactivar un webhook
POST	/api/v1/webhooks/{id}/test	webhooks:manage	Enviar un evento de prueba al webhook
GET	/api/v1/webhooks/{id}/deliveries	webhooks:manage	Ver historial de entregas y estados

Tipos de Eventos

Evento	Descripcion
evaluation.completed	Evaluacion finalizo el procesamiento IA
audio.transcribed	Transcripcion de audio completada
audio.processed	Audio completamente procesado (transcripcion + evaluacion)
voice-call.completed	Llamada del voice bot finalizada
export.ready	Exportacion de analytics lista para descargar
usage.quota_warning	Uso alcanzo el 80% de la cuota
api-key.rotated	La clave API fue rotada

Crear un Webhook

curl -X POST https://api.auralytik.ai/api/v1/webhooks \
  -H "X-Api-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/auralytik",
    "events": ["evaluation.completed", "audio.processed"],
    "description": "Production webhook"
  }'

Respuesta:

{
  "id": "wh_8f3a1b2c",
  "url": "https://your-server.com/webhooks/auralytik",
  "events": ["evaluation.completed", "audio.processed"],
  "description": "Production webhook",
  "active": true,
  "signing_secret": "whsec_k7G2...xQ9",
  "created_at": "2026-03-30T14:22:00Z"
}

Guarda el signing_secret de forma segura -- solo se retorna una vez al momento de la creacion.

Ejemplo de Payload

Cada entrega es un HTTP POST con un cuerpo JSON. La estructura externa es la misma para todos los tipos de eventos; el objeto data varia segun el evento.

{
  "id": "evt_9d4e2f1a",
  "event": "evaluation.completed",
  "timestamp": "2026-03-30T14:25:00Z",
  "data": {
    "evaluation_id": "eval_abc123",
    "engagement_id": "eng_xyz789",
    "campaign": "Customer Support Q1",
    "score": 87,
    "channel": "voice",
    "duration_seconds": 245
  }
}

Verificacion de Firma

Cada entrega de webhook incluye un encabezado X-Webhook-Signature. Siempre verifica esta firma antes de procesar el payload para asegurar que la solicitud proviene de Auralytik y no ha sido alterada.

Lee el cuerpo crudo de la solicitud (no lo parsees primero).
Calcula HMAC-SHA256(signing_secret, raw_body) y codifica el resultado en hexadecimal.
Compara el valor calculado con el encabezado X-Webhook-Signature usando una funcion de comparacion de tiempo constante para prevenir ataques de timing.
Rechaza la solicitud con un estado 401 si las firmas no coinciden.

// 1. Extract signature from header
signature = request.headers["X-Webhook-Signature"]

// 2. Compute expected signature
expected = HMAC_SHA256(signing_secret, request.raw_body)

// 3. Compare using constant-time comparison
if not constant_time_equal(expected, signature):
    return 401  // Reject the request

// 4. Process the event
process(request.body)

Politica de Reintentos

Una entrega se considera exitosa cuando tu servidor responde con un codigo de estado 2xx dentro de la ventana de timeout. Si una entrega falla, reintentamos con backoff exponencial:

Intento	Demora	Timeout
1	Inmediato	10 s
2	1 minuto	10 s
3	5 minutos	10 s

Desactivacion automatica: Si un webhook falla en todas las entregas durante 7 dias consecutivos, sera desactivado automaticamente. Puedes reactivarlo en cualquier momento a traves de la API o el dashboard.

Listo para comenzar?

Genera una clave API con el alcance webhooks:manage y registra tu primer endpoint.

Solicitar Acceso API