Definition
A webhook is an HTTP request that one system sends to a URL on another system when something happens or is needed. In a voice agent, a webhook tool is how the agent calls your own endpoint during a call.
How a webhook works
Most APIs wait to be asked. A webhook turns that around: the sending system makes an HTTP request to an address you have given it. The receiver exposes a URL, the sender calls it with a method such as POST, a set of headers and a body, and the receiver replies with a status code.
Webhooks appear in voice platforms in two ways.
- Event callbacks. The platform notifies your server about something that happened, such as a call ending, so you can store a transcript or update a record.
- Webhook tools. The agent calls your endpoint in the middle of a call, to look something up or to do something, and uses the response. This is a form of tool calling.
In Cartesia’s Managed Agents, a webhook tool is defined with a URL, an HTTP method, parameters, headers and authentication. Cartesia documents these behaviors:
- The URL must be HTTPS.
- The model decides when to call it from the tool’s description.
- Each parameter is filled by the model, a fixed value or a dynamic variable.
- The request timeout defaults to 20 seconds.
- A timeout, an unreachable endpoint or a non-2xx status returns an error result to the model, and the call continues.
Why it matters for voice agents
A webhook is the connection between the conversation and your systems, so its behavior is audible. A slow endpoint creates silence. An endpoint that fails returns an error the model has to talk about, so the response body should say what went wrong in words the agent can use.
Design the receiving side as if the caller were watching. Return short, plain text, because a long JSON dump costs the model time to read. Make operations that change data safe to repeat, since a retry or a duplicate model request should not book two appointments. Authenticate the request, and check every parameter on your server, because values the model supplies come from a conversation with a stranger.
Set the timeout against the pause a caller will accept. A 20 second timeout is a long time to stay silent on a call, so pair slow tools with a spoken line before they run.
Example
An illustrative webhook tool for an order line:
- Method and URL: GET
https://api.example.com/orders/{order_id} - Description: “Look up the status of an order by its order number.”
- Response: “Shipped Tuesday, arrives Friday.”
The model fills order_id from what the caller said and speaks the response in its own words.