Los webhooks permiten recibir notificaciones HTTP en tiempo real cuando
ocurren eventos en tu workspace. Solo se entregan eventos para agentes y
suscripciones activas.
Requiere permisos
webhooks:read para consultas y
webhooks:write para crear, actualizar o eliminar. Todos los
endpoints requieren el header X-Workspace-Id.Eventos disponibles
Los webhooks pueden suscribirse a los siguientes eventos. La lista al día siempre se puede consultar en el catálogo, conGET /v1/catalogs/items?filter=eq(type,%22webhook_event%22).
Eventos de Tools
- tool.invoked (sin emisor todavía): Se ejecuta cuando un agente termina de invocar una herramienta y recibe una respuesta.
Eventos de llamadas (Calls)
- call.callStarted: Una llamada de voz comenzó para uno de los agentes del workspace.
- call.callEnded: Una llamada de voz finalizó (incluye URLs de grabación y transcripción).
- call.callMissed (sin emisor todavía): Una llamada no fue contestada antes del timeout.
- 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): Un interlocutor dejó un mensaje de buzón de voz.
Eventos de WhatsApp
- whatsapp.messageReceived: Un usuario de WhatsApp envió un mensaje entrante al workspace.
- whatsapp.messageSent: El workspace envió un mensaje saliente de WhatsApp.
- whatsapp.messageDelivered (sin emisor todavía): Un mensaje saliente de WhatsApp llegó al dispositivo del destinatario.
- whatsapp.messageFailed (sin emisor todavía): Un mensaje saliente de WhatsApp falló al entregarse.
- whatsapp.conversationStarted (sin emisor todavía): La plataforma abrió una nueva sesión de conversación de WhatsApp.
- whatsapp.conversationEnded (sin emisor todavía): Una sesión de conversación de WhatsApp existente se cerró.
Seguridad
Todas las entregas de webhook incluyen:- HTTPS requerido: Solo se aceptan URLs HTTPS.
- Firma HMAC-SHA256: Cada request incluye el header
x-signaturecon la firma del payload. - Timestamp: Header
x-timestampcon marca temporal ISO-8601. - Secreto: El secreto se genera automáticamente (mínimo 16 caracteres) o puedes proveer el tuyo.
Verificación de firmas
Para validar que el webhook proviene de Agents Studio, verifica la firma HMAC-SHA256. Conmethod: 'POST' —el valor por defecto— se firma {timestamp}.{cuerpo crudo}:
Webhooks con method: 'GET'
Gestión de webhooks
Crear webhook
- TypeScript SDK
- cURL
Listar webhooks
- TypeScript SDK
- cURL
Obtener webhook
- TypeScript SDK
- cURL
Deliveries (historial de entregas)
Los deliveries representan cada intento de entrega de un evento a tu endpoint (incluye status, intentos, error y response status).Listar deliveries de un webhook
- TypeScript SDK
- cURL
Obtener un delivery por ID
- TypeScript SDK
- cURL
Actualizar webhook
- TypeScript SDK
- cURL
Eliminar webhook
- TypeScript SDK
- cURL
Gestión de suscripciones
Crear suscripción a evento
- TypeScript SDK
- cURL
Listar suscripciones
- TypeScript SDK
- cURL
Obtener suscripción
- TypeScript SDK
- cURL
Actualizar suscripción
- TypeScript SDK
- cURL
Eliminar suscripción
- TypeScript SDK
- cURL
Estructura de payloads
Evento: call.callEnded
Se dispara cuando una llamada de voz finaliza. Incluye información del objetivo alcanzado, URLs de grabación y transcripción.Valores de endReason y sipCode
sipCode es lo que te dice si la llamada se estableció — que alguien o algo descolgó, no
necesariamente una persona. Los códigos de la familia 2xx significan que se estableció. El 183
depende de si tu workspace tiene habilitados los valores marcados con †: sin ellos, 183 es un buzón
de voz (se estableció); con ellos, 183 es «sonó y nadie contestó» (no se estableció). La columna
«¿contestó una persona?» suele ser la que decide si hay que volver a llamar.
Estos tres campos (sipCode, endReason, durationMs) viajan igual en call.callEnded y en
call.callAnalyzed, que son dos eventos de la misma llamada: si tu integración actúa sobre
ellos, desduplica por callId.
† Estos valores se habilitan por workspace. Mientras no estén habilitados en el tuyo,
esas llamadas llegan con
endReason y sipCode en null en lugar del valor de la tabla — no con
otro código, salvo voicemail_reached y dial_no_answer, que llegan con el código entre
paréntesis fuera de él (183 y 180). Escríbenos si quieres que los habilitemos en tu workspace.Evento: call.callStarted
Se dispara cuando una llamada de voz comienza. Entrega de notificación —direction, fromNumber y toNumber van en la raíz
del payload, no bajo metadata:
toNumber ni direction, con la latencia y los
identificadores de ejecución:
isTest viaja en las dos entregas y es lo único que distingue una llamada de
prueba de una real: úsalo si no quieres que las pruebas de integración entren a
tu CRM.Evento: tool.invoked
Se dispararía cuando un agente termina de ejecutar una herramienta.Evento: whatsapp.messageReceived
Se dispara cuando se recibe un mensaje entrante de WhatsApp. El payload es plano: el teléfono del cliente escustomerPhone (no from), el
contenido es text (no message.text.body) y conversationId va en la raíz, no
bajo metadata.
buttonId llega con valor cuando el cliente respondió tocando un botón, y es
null en un mensaje de texto normal. contactFlowId identifica el ciclo de
contacto activo de ese número, o es null si no hay ninguno.Mejores prácticas
1. Procesar eventos de forma idempotente
Los webhooks pueden ser reenviados en caso de fallos. Asegúrate de que tu endpoint pueda procesar el mismo evento múltiples veces sin efectos secundarios:Esta clave deduplica los reintentos de una misma entrega, que repiten el
timestamp. No colapsa las dos entregas de call.callStarted —cada una sella
el suyo— y no debería: llevan datos distintos y las dos te interesan.2. Responder rápidamente
Responde con2xx lo antes posible y procesa el evento de forma asíncrona:
3. Reintentos automáticos
El sistema reintenta entregas fallidas hasta 5 veces con backoff exponencial:- Intento 1: inmediato
- Intento 2: ~2 segundos después
- Intento 3: ~4 segundos después
- Intento 4: ~8 segundos después
- Intento 5: ~16 segundos después
2xx se consideran exitosas.
4. Monitorear entregas
Usa los campossuccessCount, failureCount y lastDeliveryAt del webhook para monitorear la salud:
5. Filtrar por agente
Si solo necesitas eventos de un agente específico, configuraagentId al crear el webhook:
