Webhooks

Los webhooks te permiten recibir notificaciones HTTP en tiempo real cuando ocurren eventos en tu tenant de VOCALS. Configura una URL y suscribete a tipos de eventos especificos; VOCALS enviara un payload JSON mediante POST a tu endpoint cada vez que se dispare un evento coincidente.

Tipos de Evento

Evento	Descripcion
call.started	Una llamada ha comenzado (entrante o saliente)
call.ended	Una llamada ha terminado
call.failed	Una llamada fallo debido a un error
transcript.ready	La transcripcion completa de una llamada esta disponible

Listar Webhooks

GET /webhooks

Devuelve todas las configuraciones de webhooks del tenant actual, ordenadas por fecha de creacion.

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/vocals-webhook",
    "events": ["call.started", "call.ended"],
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
]

Campos de Respuesta

Campo	Tipo	Descripcion
id	uuid	ID de configuracion del webhook
url	string	URL de destino para los payloads de eventos
events	array	Lista de tipos de eventos suscritos
is_active	boolean	Si el webhook esta activo
created_at	datetime	Marca de tiempo de creacion
updated_at	datetime	Marca de tiempo de ultima actualizacion

Crear Webhook

POST /webhooks

Cuerpo de la Solicitud

{
  "url": "https://example.com/vocals-webhook",
  "events": ["call.started", "call.ended", "transcript.ready"],
  "is_active": true
}

Campos de la Solicitud

Campo	Tipo	Requerido	Por defecto	Descripcion
url	string	Si	--	URL HTTPS para recibir payloads de webhook
events	array	Si	--	Tipos de eventos a los que suscribirse
is_active	boolean	No	true	Si el webhook esta activo

Respuesta

201 Created -- Devuelve el objeto WebhookResponse.

Actualizar Webhook

PUT /webhooks/{webhook_id}

Se soportan actualizaciones parciales. Solo incluye los campos que deseas cambiar.

Cuerpo de la Solicitud

{
  "url": "https://new-url.example.com/webhook",
  "events": ["call.ended"],
  "is_active": false
}

Campos de la Solicitud

Campo	Tipo	Requerido	Descripcion
url	string	No	URL de destino actualizada
events	array	No	Suscripciones de eventos actualizadas
is_active	boolean	No	Activar o desactivar el webhook

Respuesta

200 OK -- Devuelve el WebhookResponse actualizado.

Eliminar Webhook

DELETE /webhooks/{webhook_id}

Elimina permanentemente una configuracion de webhook y su historial de entregas.

Respuesta

204 No Content

Registros de Entrega

GET /webhooks/{webhook_id}/deliveries

Devuelve una lista paginada de intentos de entrega para un webhook especifico, ordenados por mas recientes primero. Usalo para solucionar problemas de entregas fallidas.

Parametros de Consulta

Parametro	Tipo	Por defecto	Descripcion
page	integer	1	Numero de pagina
page_size	integer	20	Elementos por pagina (maximo 100)

Respuesta

{
  "items": [
    {
      "id": "660e8400-...",
      "event_type": "call.ended",
      "status_code": 200,
      "attempts": 1,
      "last_attempt_at": "2026-03-01T14:32:50Z",
      "created_at": "2026-03-01T14:32:45Z"
    },
    {
      "id": "770e8400-...",
      "event_type": "call.started",
      "status_code": 500,
      "attempts": 3,
      "last_attempt_at": "2026-03-01T14:31:15Z",
      "created_at": "2026-03-01T14:30:05Z"
    }
  ],
  "total": 85,
  "page": 1,
  "page_size": 20
}

Campos del Registro de Entrega

Campo	Tipo	Descripcion
id	uuid	ID del registro de entrega
event_type	string	El evento que disparo esta entrega
status_code	integer | null	Codigo de estado HTTP del endpoint del webhook (null si no hubo respuesta)
attempts	integer	Numero de intentos de entrega
last_attempt_at	datetime | null	Marca de tiempo del intento mas reciente
created_at	datetime	Cuando se disparo la entrega por primera vez