Definição
Um webhook é uma requisição HTTP que um sistema envia a uma URL de outro sistema quando algo acontece ou é necessário. Em um agente de voz, uma ferramenta webhook é como o agente chama o seu próprio endpoint durante uma chamada.
Como um webhook funciona
A maioria das APIs espera ser consultada. Um webhook inverte isso: o sistema emissor faz uma requisição HTTP para um endereço que você lhe deu. O receptor expõe uma URL, o emissor a chama com um método como POST, um conjunto de cabeçalhos e um corpo, e o receptor responde com um código de status.
Os webhooks aparecem nas plataformas de voz de duas formas.
- Callbacks de eventos. A plataforma avisa seu servidor sobre algo que aconteceu, como o fim de uma chamada, para você guardar uma transcrição ou atualizar um registro.
- Ferramentas webhook. O agente chama seu endpoint no meio de uma chamada, para consultar algo ou fazer algo, e usa a resposta. É uma forma de chamada de ferramentas.
No Managed Agents da Cartesia, uma ferramenta webhook é definida com uma URL, um método HTTP, parâmetros, cabeçalhos e autenticação. A Cartesia documenta estes comportamentos:
- A URL deve ser HTTPS.
- O modelo decide quando chamá-la a partir da descrição da ferramenta.
- Cada parâmetro é preenchido pelo modelo, por um valor fixo ou por uma variável dinâmica.
- O tempo limite da requisição é de 20 segundos por padrão.
- Um tempo limite esgotado, um endpoint inalcançável ou um status diferente de 2xx devolve um resultado de erro ao modelo, e a chamada continua.
Por que importa para agentes de voz
Um webhook é a conexão entre a conversa e seus sistemas, então o comportamento dele é audível. Um endpoint lento cria silêncio. Um endpoint que falha devolve um erro sobre o qual o modelo precisa falar, então o corpo da resposta deve dizer o que deu errado com palavras que o agente possa usar.
Projete o lado receptor como se quem liga estivesse olhando. Devolva texto curto e simples, porque um despejo longo de JSON custa tempo de leitura ao modelo. Torne as operações que alteram dados seguras de repetir, já que uma nova tentativa ou uma requisição duplicada do modelo não deve marcar duas consultas. Autentique a requisição e confira cada parâmetro no seu servidor, porque os valores fornecidos pelo modelo vêm de uma conversa com um desconhecido.
Defina o tempo limite de acordo com a pausa que quem liga aceitará. Um tempo limite de 20 segundos é muito para ficar em silêncio numa chamada, então combine as ferramentas lentas com uma frase falada antes de rodá-las.
Exemplo
Uma ferramenta webhook ilustrativa para uma linha de pedidos:
- Método e URL: GET
https://api.example.com/orders/{order_id} - Descrição: “Consulta o status de um pedido pelo número do pedido.”
- Resposta: “Enviado na terça, chega na sexta.”
O modelo preenche order_id com o que quem ligou disse e fala a resposta com as próprias palavras.