Inbound webhook (pre-call)

With the inbound webhook we call your server as soon as a call arrives, before the greeting. The JSON you return is used by the assistant during that conversation, for example to greet the caller by name or mention an open invoice.

When is it called?

• Incoming phone calls: on every call the assistant accepts, before the greeting, including unknown numbers. The caller waits until your server has responded.
• SMS, WhatsApp and webchat: never.
• Outbound calls: never. There you pass variables yourself through the campaign or the API; see Outbound calls.
• Try it out: never. So test the webhook with a real call.

A call that is rejected, for example from a blocked contact, does not call the webhook. A condition on the action has no effect here: if the action is on, it runs on every call to that assistant.

The request

With an empty Body template we send a POST with this JSON body and the X-Yarla-Signature header (see Webhooks for verifying the signature). The full stop is literally part of the field name.

{
  "fromNumber": "+31612345678",
  "toNumber": "+31201234567",
  "personNumber": "+31612345678",
  "agentNumber": "+31201234567",
  "company.name": "Jansen Plumbing",
  "company.website": "https://www.example.com",
  "company.phone": "+31201234567",
  "company.email": "info@example.com",
  "company.address": ""
}

Field	Meaning
personNumber, fromNumber	The caller's number (E.164). Both fields hold the same value.
agentNumber, toNumber	Your number that was called. Both fields hold the same value.
company.name	Your business name.
company.website, company.phone, company.email	Your website and the phone number and email address for customers. Empty if you have not filled them in.
company.address	Your address, only when Share this address with customers is on. Otherwise empty.

Other details, such as the conversation id or the channel, are not included. In your own Body template you can only use these fields, for example {{personNumber}} or {{company.name}}; other variables such as {{conversationId}} stay empty. A GET request has no body and is not signed, so preferably leave the method on POST.

The action's Authorization key is not sent with this request. If your endpoint expects a key, put it under Headers, for example X-Api-Key: …. That value stays readable in the form.

The response

Respond with a 2xx status, for example 200, and a JSON object, preferably flat: keys with strings, numbers or booleans.

{
  "customerName": "Jan de Vries",
  "customerId": "C-1042",
  "openInvoice": true,
  "lastVisit": "2026-06-12"
}

Rules:

• An empty object {}, a status outside 2xx, a response that is not a JSON object (such as a list or plain text) or a timeout (3 seconds) means no context. The assistant simply starts without it; the conversation always continues. A failed request is not retried.
• Nested objects stay nested: you use { "customer": { "name": "Jan" } } as {{customer.name}}.
• Do not use arrays. Convert a list to readable text yourself, for example "openInvoices": "2 invoices, total € 340".
• Keep it small: a handful of fields. Everything you return becomes part of the prompt. A response longer than 20,000 characters is cut off and can then no longer be read.
• If you have several actions before the call, they run one after the other and their responses are merged. For the same field name the last response applies. Each action gets 3 seconds, so the caller waits longer.

Using the context

In the greeting. There the fields are available directly under their own name, for example {{customerName}}. The longer form {{inboundContext.customerName}} stays empty there.

In the prompt. The assistant receives all fields as context during the call by itself. They do not work as variables in the prompt: {{customerName}} stays empty there. So simply refer to the field by name, as in the example under Set it up.

In actions during the conversation. An HTTP request or Google Sheets action during the conversation cannot use these fields as variables. If you need such a value there, make it a parameter under Parameters the assistant fills.

In actions after the conversation. In email, SMS, HTTP request and Google Sheets actions always use the form {{inboundContext.customerName}}. In the default body of the webhook after the call all fields sit under inboundContext.

In the Inbox. On the conversation you see the returned fields under Technical details, at Details looked up before the call, so you can check what the assistant knew. A failed request only shows there as {}: What the actions did only lists actions after the conversation.

If a field is missing, the variable is empty. Because the greeting is fixed text, "Good afternoon, {{customerName}}" reads oddly when there is no name. Leave the use of the name to a rule in the prompt instead.

Set it up

1. Open the assistant under Assistants, go to the Tasks tab, open the Actions card and click Add new. This takes the Editor or Admin role.
2. Choose HTTP request.
3. Give the action a Name and under When choose Before the call.
4. Under URL enter the address of your endpoint, preferably with https://. Internal and private addresses are refused. Leave the Method on POST and the Body template empty to send the default request shown above.
5. The action saves automatically once it has a name and a valid web address. Then click Close.
6. Call the assistant's number and check in the Inbox that Technical details shows the expected fields.

Then, on the Instructions tab, add a rule under Important rules (in Advanced mode: under Full prompt), for example:

If customerName is known, address the caller by name and ask whether it concerns the known address.
If customerName is empty or missing, ask for the name first.
If openInvoice is true, politely mention the open invoice before booking a new appointment.

Tips

• Respond within 3 seconds. Look up by phone number using an index or cache, and do no more than one lookup per request.
• Unknown number? Return {} with status 200. An error status has the same effect.
• Never return secrets or sensitive data such as passwords, bank details or national ID numbers. Everything you return goes into the prompt and is visible in the Inbox and through the API.
• Normalise the number on your side: personNumber is in E.164 (+31612345678), your CRM may not be. For a withheld number the field can be empty or hold something that is not a phone number.
• No server of your own? With Make or n8n you can look up a contact in HubSpot or Google Sheets and return the answer without code; see Make & n8n recipes.

Related articles

• HTTP request action
• How to write a great prompt
• Make & n8n recipes
• Webhooks