Notificaciones de llamada

Las notificaciones de telefonía se entregan por el mismo mecanismo de webhooks que el resto de los eventos del workspace. Esta página es el camino corto para el caso más común; el contrato completo —firma, reintentos, entregas— está en Webhooks.

1 · Crea el webhook

Requiere el scope webhooks:write y el header X-Workspace-Id. La URL debe ser HTTPS.

curl --request POST \
  --url "$API_BASE_URL/v1/webhooks" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://tu-dominio.mx/hooks/agents-studio",
    "description": "Notificaciones de llamada",
    "isActive": true
  }'

El webhook no tiene campo name: la etiqueta legible es description. El cuerpo se valida en modo estricto, así que cualquier campo que no esté en el contrato —name incluido— se rechaza con 400 antes de crear nada.

La respuesta trae el id del webhook —un UUID— que se usa en el siguiente paso.

2 · Suscríbete a los eventos de llamada

Cada evento se suscribe por separado, con su eventKey:

`eventKey`	Cuándo llega
`call.callStarted`	La llamada comenzó (llega dos veces: ver Webhooks)
`call.callEnded`	La llamada terminó, con grabación y transcripción
`call.callMissed`	Sin emisor todavía: la suscripción se crea, pero no llega nada
`call.callAnalyzed`	El análisis posterior a la llamada ya está disponible
`call.transferBridged`	Una transferencia se conectó con el destino
`call.voicemailReceived`	Sin emisor todavía: la suscripción se crea, pero no llega nada

curl --request POST \
  --url "$API_BASE_URL/v1/webhooks/$WEBHOOK_ID/subscriptions" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "eventKey": "call.callEnded",
    "isActive": true
  }'

Respuesta 201 Created

{
  "id": "5f3a91c4-8d2b-4e17-9c05-1a7b6e2d4f80",
  "webhookId": "c7d90b21-4e58-4a63-9f12-8b3c5d6e7a91",
  "eventKey": "call.callEnded",
  "isActive": true,
  "createdAt": "2026-08-19T16:00:05.000Z",
  "updatedAt": "2026-08-19T16:00:05.000Z"
}

Los identificadores de webhook y de suscripción son UUID v4. Un valor con otro formato se rechaza con 400 antes de llegar al dominio.

Para ver los eventKey disponibles al día, consulta el catálogo: GET /v1/catalogs/items?filter=eq(type,%22webhook_event%22).

3 · Recibe el evento

Esto es lo que llega a tu endpoint cuando termina una llamada:

{
  "event": "call.callEnded",
  "timestamp": "2026-08-19T16:04:31.902Z",
  "workspaceId": "00000000-1111-2222-3333-444455556666",
  "agentId": "38f62697-0f4b-49bc-8a0c-67256f5af6ff",
  "callId": "9f2c7b41-6d18-4a2e-8b05-3c9e1d7f4a62",
  "contactFlowId": null,
  "status": "ended",
  "sipCode": 200,
  "endReason": "user_hangup",
  "startedAt": "2026-08-19T16:02:58.000Z",
  "endedAt": "2026-08-19T16:04:31.000Z",
  "durationMs": 93000,
  "variables": { "nombre": "María" },
  "outputVariables": { "acepto_cita": "true" },
  "result": {
    "goal": {
      "achieved": true,
      "reason": "El cliente aceptó la cita del jueves a las 10:00"
    },
    "recordingRoute": "s3://.../9f2c7b41.mp3",
    "transcriptionRoute": "s3://.../9f2c7b41.json"
  },
  "metadata": {
    "toNumber": "+525512345678",
    "createdAt": "2026-08-19T16:02:58.000Z",
    "startedAt": "2026-08-19T16:02:58.000Z",
    "endedAt": "2026-08-19T16:04:31.000Z",
    "executionId": "0b6f2d18-7c39-4e51-a8d2-5f4b3c9e1a70"
  }
}

Las variables que el agente recolectó durante la conversación llegan en outputVariables, y las que se le pasaron al iniciar la llamada en variables. result.goal es un objeto, no una cadena: el booleano achieved dice si se cumplió el objetivo de la llamada y reason lo explica en prosa. Compara contra payload.result.goal.achieved.

4 · Verifica la firma

Cada entrega incluye dos headers: x-timestamp con la marca ISO-8601 y x-signature con el HMAC-SHA256, en base64, de la cadena {timestamp}.{cuerpo crudo} usando el secreto del webhook.

import { createHmac, timingSafeEqual } from 'node:crypto';

function isValid(rawBody: string, headers: Record<string, string>, secret: string) {
  const expected = createHmac('sha256', secret)
    .update(`${headers['x-timestamp']}.${rawBody}`)
    .digest('base64');

  const received = Buffer.from(headers['x-signature'] ?? '', 'utf8');
  const computed = Buffer.from(expected, 'utf8');

  return (
    received.length === computed.length && timingSafeEqual(received, computed)
  );
}

Firma sobre el cuerpo crudo, antes de parsear el JSON: volver a serializar el objeto cambia los bytes y la comparación falla.

Esto vale para un webhook POST, que es el valor por defecto. Si lo creas con method: 'GET' no hay cuerpo —el evento viaja como query string— y la firma se calcula sobre la URL completa; el detalle está en Webhooks.

5 · Depura lo que no llegó

Cada intento de entrega queda registrado, con su código de respuesta y su cuerpo:

curl --request GET \
  --url "$API_BASE_URL/v1/webhooks/$WEBHOOK_ID/deliveries" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID"

Sólo se entregan eventos de agentes y suscripciones activas: si un evento no aparece, revisa primero que la suscripción y el webhook tengan isActive: true.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

1 · Crea el webhook

2 · Suscríbete a los eventos de llamada

3 · Recibe el evento

4 · Verifica la firma

5 · Depura lo que no llegó

​1 · Crea el webhook

​2 · Suscríbete a los eventos de llamada

​3 · Recibe el evento

​4 · Verifica la firma

​5 · Depura lo que no llegó

1 · Crea el webhook

2 · Suscríbete a los eventos de llamada

3 · Recibe el evento

4 · Verifica la firma

5 · Depura lo que no llegó