Webhook during the call
A webhook during the call hands the assistant a "tool": the moment the caller asks for something that lives in your system, the assistant calls your endpoint and works the answer into the conversation. This article explains how to set up such a tool and what goes over the wire.
When is it called?
The assistant decides on its own, based on what you enter at When should the assistant use this?, whether the tool is needed. For example: "When the caller asks about the status of an order and mentions an order number." The assistant first collects the parameters you marked as required (asking for them if the caller has not mentioned them yet) and then makes the request. As soon as the response arrives, the conversation continues.
One conversation can call the tool several times, for example when the caller mentions two order numbers. The tool works on every channel, so also in SMS, WhatsApp and webchat.
Set it up
You need the Editor or Admin role for this.
- Open the assistant under Assistants, go to the Tasks tab and expand the Actions card. Click Add new and choose HTTP request.
- At Name, give the action a clear name (for example "Look up order status") and at When, choose During the conversation.
- Choose the Method and enter the URL of your endpoint. If your system needs them, also fill in Headers or an Authorization key.
- Leave the Body template empty to send the default request shown below, or build your own body using
{{orderNumber}}. - At Parameters the assistant fills, use Add variable to add your parameters: for each one a name, a type and a description that tells the AI model what to fill in.
- Fill in a Response hint.
- At the bottom, fill in When should the assistant use this?.
Changes are saved automatically as soon as the action has a name and a valid web address. In Try it out the request is only really sent when Perform actions for real is on. Otherwise the assistant gets a simulated response.
| Setting | Meaning | Default |
|---|---|---|
| When should the assistant use this? | When the assistant uses the tool. Write it as a sentence for the AI model. | Empty: the assistant then goes by the name of the action alone |
| Parameters the assistant fills | The data the assistant extracts from the conversation and sends along. Per parameter: name (letters, digits and underscores, with a letter as the first character), type (string, number, boolean), description and whether it is required. | None |
| Response hint | Guidance for the AI model on what your answer contains and how to use it, for example "Mention the status and the expected delivery date in plain language. Do not read out internal field names." | Empty |
On a phone call, the assistant can say in a few words that it is checking while the request runs.
Example parameter:
| Name | Type | Description |
|---|---|---|
orderNumber | string | The order number the caller mentions, for example A-2231. Always a letter, a dash and four digits. |
A good description stops the assistant from mistaking a postcode or phone number for an order number.
The request
By default we send a POST with JSON. Every request with a body gets the X-Yarla-Signature header (see Webhooks). A GET request has no body and is not signed. Put the parameters in the URL instead, for example https://api.example.com/orders/{{orderNumber}}.
With an empty Body template, the parameters are separate fields in a JSON object:
{ "orderNumber": "A-2231" }Data that already belongs to the conversation can come along too, as fields at the same level: for example the variables of a campaign or an API call, the name on a call you start from a contact, or the WhatsApp profile name of an unknown contact. Ignore fields you do not recognise. A parameter that is not required and that the assistant does not know is null or missing.
In your own body you use the parameters as variables:
{ "reference": "{{orderNumber}}" }No built-in variables
Built-in variables such as {{personNumber}} and {{conversationId}} stay empty during the conversation. On most phone calls you do not get what was looked up before the call either, so do not rely on it. To check that the order belongs to this customer, add a parameter for the caller's number, for example callerNumber with the description "The caller's phone number". In webchat the assistant only knows that number if the visitor mentions it.
The response
Respond with a status in the 2xx range, for example 200, and either JSON or plain text. The response is handed verbatim to the AI model as the tool result; the assistant phrases it in its own words.
{ "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }Plain text works too:
Order A-2231 was shipped on 12 September with PostNL and will be delivered on 14 September.- Keep it small. The assistant receives at most 6,000 characters; the rest is dropped. Send only what the assistant needs; no full database records.
- Make values readable. A date like
2026-09-14is spoken well; a Unix timestamp is not. - Nothing found? Respond with
200and a clear message, such as{ "found": false, "message": "No order with number A-2231" }. That lets the assistant say so politely and ask for another number. - Reserve error statuses for genuine errors on your side.
Error handling
On a status outside 2xx, the assistant only hears the status code; it does not receive the content of your response. It does not make anything up then: it says it does not know and offers to have the team get back to the caller.
We wait 6 seconds for your endpoint, and you cannot change this. If your endpoint does not respond in time or cannot be reached, in a text conversation the assistant is told the lookup failed. On most phone calls it then gets no result at all, so it does not know that the request failed. Make sure your endpoint responds well within the time. We do not retry the request.
The status code and response of a call during the conversation are not shown in the dashboard. In the Inbox, under Technical details on the conversation, What the actions did only lists the actions after the conversation. So keep your own log on your endpoint.
Add to the Response hint or on the Instructions tab what the assistant should do when the lookup fails, for example: "If the lookup does not succeed, offer to have a colleague call back."
Example conversation
Caller: I'd like to know where my order is, order number A-2231.
→ POST to your endpoint: { "orderNumber": "A-2231" }
← { "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }
Assistant: Your order A-2231 has been shipped with PostNL and will be
delivered on 14 September. Is there anything else I can help with?Alternative: Google Sheets
If the data lives in a spreadsheet you do not need an endpoint of your own: with the Google Sheets action the assistant looks up a row during the call. A webhook is the better choice when the data lives in a CRM, web shop or your own database, or when something has to be calculated first.