Definición
Un webhook es una petición HTTP que un sistema envía a una URL de otro sistema cuando ocurre algo o hace falta algo. En un agente de voz, una herramienta webhook es la forma en que el agente llama a tu propio endpoint durante una llamada.
Cómo funciona un webhook
La mayoría de las API esperan a que se les pregunte. Un webhook le da la vuelta: el sistema emisor hace una petición HTTP a una dirección que tú le has dado. El receptor expone una URL, el emisor la llama con un método como POST, unas cabeceras y un cuerpo, y el receptor responde con un código de estado.
Los webhooks aparecen en las plataformas de voz de dos maneras.
- Retrollamadas de eventos. La plataforma avisa a tu servidor de algo que ocurrió, como el fin de una llamada, para que guardes una transcripción o actualices un registro.
- Herramientas webhook. El agente llama a tu endpoint a mitad de una llamada, para consultar algo o hacer algo, y usa la respuesta. Es una forma de llamada a herramientas.
En los Managed Agents de Cartesia, una herramienta webhook se define con una URL, un método HTTP, parámetros, cabeceras y autenticación. Cartesia documenta estos comportamientos:
- La URL debe ser HTTPS.
- El modelo decide cuándo llamarla a partir de la descripción de la herramienta.
- Cada parámetro lo rellena el modelo, un valor fijo o una variable dinámica.
- El tiempo de espera de la petición es de 20 segundos por defecto.
- Un tiempo de espera agotado, un endpoint inalcanzable o un estado distinto de 2xx devuelve un resultado de error al modelo, y la llamada continúa.
Por qué importa para los agentes de voz
Un webhook es la conexión entre la conversación y tus sistemas, así que su comportamiento se oye. Un endpoint lento crea silencio. Uno que falla devuelve un error del que el modelo tiene que hablar, así que el cuerpo de la respuesta debe decir qué salió mal con palabras que el agente pueda usar.
Diseña el lado receptor como si quien llama estuviera mirando. Devuelve texto corto y llano, porque un volcado largo de JSON cuesta tiempo de lectura al modelo. Haz que las operaciones que cambian datos sean seguras de repetir, ya que un reintento o una petición duplicada del modelo no debe reservar dos citas. Autentica la petición y comprueba cada parámetro en tu servidor, porque los valores que aporta el modelo proceden de una conversación con un desconocido.
Fija el tiempo de espera según la pausa que aceptará quien llama. Un tiempo de espera de 20 segundos es mucho para quedarse en silencio en una llamada, así que combina las herramientas lentas con una frase hablada antes de ejecutarlas.
Ejemplo
Una herramienta webhook ilustrativa para una línea de pedidos:
- Método y URL: GET
https://api.example.com/orders/{order_id} - Descripción: «Consulta el estado de un pedido por su número de pedido».
- Respuesta: «Enviado el martes, llega el viernes».
El modelo rellena order_id con lo que dijo quien llama y dice la respuesta con sus propias palabras.