dynamic_variables when you create the call, and the agent’s prompt resolves {{first_name}} to the right name.
Inbound calls are harder — the caller arrives unannounced. Without a webhook, an agent whose prompt says Hi {{first_name}} has nothing to fill that placeholder with, and the caller hears the placeholder read out literally.
The inbound call webhook closes that gap. Set a URL on a phone number, and Verbeo calls it once per inbound call — before the agent picks up. Your backend looks the caller up in your own CRM and replies with two things:
That second field is what lets a single number serve more than one agent — route existing customers to a support agent and unknown numbers to a sales agent, decided per call.
Set the webhook URL
1
Open the Phone Numbers page
In the Verbeo dashboard, go to Phone Numbers and click the pencil icon on the number you want to configure.
2
Fill in the webhook URL
Under Inbound Call Webhook, set Webhook URL (POST) to your HTTPS endpoint.
3
Save
Click Update. The webhook takes effect on the next inbound call — there is nothing to redeploy.
The field appears on numbers connected through SIP trunking. If you don’t see it, your number is on the legacy Twilio path — see Import a phone number from Twilio to move it onto a trunk.
What Verbeo sends
VerbeoPOSTs this JSON to your URL:
string
required
Always
"call_inbound". Branch on this field — more event types may be added later.integer
required
Unix timestamp in milliseconds when Verbeo sent the request.
string
required
UUID of the agent currently assigned to this number for inbound calls. This is the agent that will answer unless you override it.
string
required
The caller’s number in E.164 format. This is your lookup key.
string
required
The Verbeo number that was dialed, in E.164 format.
There is no
call_id in this payload. The call does not exist yet — Verbeo is still deciding how to answer it. Correlate with the call_id that arrives in the call_started webhook moments later.What you return
Reply with200 OK and a JSON body. Every field is optional — returning {} means “answer normally,” which is exactly what you should do for a caller you don’t recognize.
object
Key-value pairs substituted into the agent’s system prompt wherever it references
{{key}}. Values should be strings; numbers and booleans are converted for you. Nested objects and arrays are dropped.Up to 100 variables, each value up to 2000 characters. Keys beginning with __ are reserved by Verbeo and ignored.string
UUID of a different agent to answer this call. Must belong to the same workspace as the phone number — an agent from another workspace is ignored and the default agent answers instead.
When something goes wrong
The webhook never blocks a call. If it times out, refuses the connection, returns a non-2xx status, or returns a body Verbeo cannot parse, the call connects normally using the number’s assigned inbound agent with no dynamic variables.
That fail-open behaviour means a broken endpoint degrades personalization, never availability — but it also means a silently failing webhook looks like “the variables stopped working.” Check your endpoint first when callers start hearing placeholders.
If you are migrating from another platform that retries this webhook, note that Verbeo does not. A single 5s attempt either answers or falls open — the call is never held up waiting on a second try.
Missing variables
If your prompt references{{first_name}} and your response does not include it, the placeholder is passed to the model verbatim — the caller may hear it read aloud. Verbeo does not blank out unresolved placeholders, matching the behaviour of other platforms.
Two ways to stay safe:
- Always return every variable your prompt uses, falling back to a neutral value (
"first_name": "there") when you have no data. - Or write prompts that read naturally when a value is generic, rather than depending on a name being present.
Example handler
Express