Inbound Webhook

Overview

The Inbound Webhook sends an HTTP request before the voice agent accepts an incoming call. Values from the JSON response become variables. You can use them in the initial greeting, the AI instruction (user prompt), a call-forwarding destination, and post-processing. Typical examples include the customer’s name, plan, customer ID, or the phone number of their account contact. The voice agent can use this information to greet callers personally, answer with relevant context, and forward them to the right destination.

The Inbound Webhook only runs for incoming calls. The HTTP request must finish before the voice agent accepts the call.

Open the Inbound Webhook

Open the voice agent

Open the voice agent you want and switch to the Advanced tab.

Configure the Inbound Webhook

Open the Inbound Webhook card and click Configure.

Enable the feature

Once you have saved a valid configuration, use the toggle on the card to enable or pause the Inbound Webhook.

1. Configure the connection

In the first step, choose when and how the HTTP request is sent.

Timeout

The timeout determines the maximum time the system waits for the API. You can enter a value between 250 ms and 30,000 ms (30 seconds). The default is 5,000 ms. A longer timeout gives a slow API more time, but it also delays call acceptance. Use the lowest value at which your API responds reliably.

Behavior on error or timeout

Under On error or timeout, two options are available:

Option	Behavior
Continue call with default values	The call is accepted. Each unavailable variable uses its configured default value. A variable without a default remains empty.
Do not accept call	The voice agent does not accept the call if the HTTP request fails or exceeds the timeout.

For most use cases, Continue call with default values is the more robust setting. The voice agent remains reachable even if the connected system is temporarily unavailable.

HTTP method and endpoint

The available HTTP methods are GET, POST, PUT, PATCH, and DELETE. The endpoint URL must start with https://.

System variables can be used in the URL path or query string, for example https://api.example.com/customers/{{caller_number}}.
With POST, PUT, PATCH, and DELETE, you can also configure a JSON body.
GET requests are sent without a request body.

Authentication

The Inbound Webhook supports no authentication, Bearer token, API key header, Basic auth, OAuth 2.0, and JWT OAuth. For OAuth 2.0 and JWT OAuth, select an existing saved connection. Credentials are not shown in the technical test details.

Send call data as system variables

The following system variables are available before the call:

Variable	Meaning
`{{caller_number}}`	Phone number of the incoming caller. The value can be empty for anonymous calls.
`{{called_number}}`	The customer-facing destination number reached by the caller.
`{{forwarded_from_number}}`	Forwarding identifier supplied by the telephony provider, if available. It can contain a phone number or a technical identifier.

You can use these variables in the endpoint URL, in additional headers, and - for methods with a request body - in the JSON body. Click a supported field and type {{. Then select the required variable from the list. Example additional header:

Key	Value
`X-Customer-Number`	`{{caller_number}}`

If call information is unavailable, an empty value is inserted. The placeholder itself is never sent to your API.

In the Inbound Webhook HTTP request, use the system variables shown above without a namespace, for example {{caller_number}}. Use values from the API response with pre_call afterwards, for example {{pre_call.first_name}}.

2. Test the connection and inspect the response

In the second step, you can call your real API with sample data of your choice. All three phone number fields are optional and affect this test only.

Optional sample data for the HTTP request

caller_number simulates the caller’s phone number.
called_number simulates the called destination number.
forwarded_from_number simulates a forwarded call.

Enter the values your API needs for a realistic test and click Run test. In the test, these values replace the matching placeholders in the URL, headers, and JSON body. After a successful test, you see the HTTP status and request duration. Below that, you can select individual values directly from the response. Each selected value becomes an Inbound Webhook variable in the third step.

Select fields directly from the test response

Technical details

Open Technical details to inspect two views side by side:

Final request preview shows the method, URL, headers, and body after system variables have been replaced. Sensitive authentication values are redacted.
JSON response shows the response returned by your API during the test.

Search the response

For large responses, search by field name, response path, or value. Then select the required scalar field using its checkbox.

Only scalar values can become variables: text, numbers, and true or false. For objects and arrays, select the specific value inside the structure.

Dot notation for nested responses and arrays

Response paths use dot notation. Each dot moves one level deeper. For arrays, the index is also a path segment and starts at 0. Examples:

Content	Response path
Field `firstName` in the first item of the `users` array	`users.0.firstName`
Field `sku` of the second item in the first order	`orders.0.items.1.sku`
Nested company address	`company.address.address`

The selection list shows at most the first 1,000 scalar response fields. For larger responses, use search or manually enter a known dot path in the next step.

Configure without a successful test

Testing is optional. If your API cannot be tested from the configuration dialog, continue to the Variables step. Create the variable name there and manually enter the expected response path using dot notation.

3. Define variables and default values

In the final step, review and edit the variable mappings.

Variable names, response paths, and default values

Field	Meaning
Variable	The name you later use as a placeholder, for example `first_name`. In other fields, use it as `{{pre_call.first_name}}`.
Response path	The exact position of the value in the JSON response, for example `users.0.firstName`.
Default value	Optional replacement value used when no usable value is found at the response path.

The default value is used when the path is missing, the value is null or empty, or the path points to an object or array instead of a scalar value. If Continue call with default values is selected, default values are also used when the request fails or times out. Without a default value, the variable remains empty. The greeting never reads out an unresolved placeholder such as {{pre_call.first_name}}.

Use variables in the voice agent

Save the Inbound Webhook configuration. A variable named first_name is then available as {{pre_call.first_name}}. In a supported field, type {{ and select the variable.

Area	Example	Use
Initial greeting	`Hallo {{pre_call.first_name}}, wie kann ich helfen?`	Greet the caller with relevant information immediately.
AI instruction (user prompt)	`Der Tarif des Kunden ist {{pre_call.plan}}.`	Give the agent context for the conversation; also available in the fullscreen editor.
Tools → Forward calls → Phone number	`{{pre_call.forward_to}}`	Use a phone number from your API as the forwarding destination.
Post-processing	`Kunden-ID: {{pre_call.customer_id}}`	Use the loaded value in email subjects and bodies, SMS, AI content instructions, and API URLs, header values, and bodies.

Initial greeting and AI instruction

For every incoming call, the HTTP request runs first. Placeholders are populated with the response values or configured defaults. These values are also available for forwarding and post-processing within the same call. For more on the user prompt, see AI instructions.

Dynamic forwarding destination

For example, create a variable named forward_to and map it to the phone-number field in your API response. Under Tools → Forward calls, enter the complete placeholder {{pre_call.forward_to}} in Phone number. The resolved value must be a phone number in international format with + and the country code, without spaces, for example +493012345678. National formats such as 03012345678 and values such as +49 30 12345678 are not supported. Do not combine the placeholder with an additional country code or other text.

Post-processing with the same values

Use {{pre_call.customer_id}}, for example, to associate a post-processing task with the correct customer. These values come from the Inbound Webhook before the conversation. Custom extractions such as {{post_call.kunden_email}} are produced only after the conversation, so they are unavailable in the greeting, user prompt, or forwarding destination.

API response requirements

For the response to be processed, your API must:

respond with an HTTP status from 200 through 299,
return a valid JSON object,
provide the required values as text, numbers, or Boolean values.

Missing, empty, or unusable values follow the configured default-value and failure behavior.

Getting Started

AI Assistants

AI Content & Context

Advanced Features

Tickets

Team

Agent Templates

Overview

Open the Inbound Webhook