Overview
Build a webhook that carries a value your AI agent captures on the call into the system your team already works in. No engineering ticket required.
In this guide
- Build the webhook — define the endpoint, the authentication, and the VIN field
- Test it — send a real request and inspect exactly what went out
- Place it in your call flow — add the tool to a workflow, store the VIN as a variable, and branch on the result
What you're building
A webhook tool is a connection you define once: an endpoint, an authentication header, and the fields you want sent. Your AI agent then fills those fields from the conversation and posts them to your system.
This guide walks through one complete example. You'll define a field called VIN, describe it well enough that the agent knows how to pull it out of a spoken conversation, send it to your CRM, and then place the whole thing inside a call flow.
The example throughout this guide is that of a vehicle's VIN.
Before You Begin
- A CRM endpoint that accepts an HTTPS
POSTrequest. Publicly reachable addresses only — internal or private-network addresses are blocked for security.- POST for creating or updating a record; GET for looking something up
- Whatever your CRM uses to authenticate, typically an API key or bearer token.
- About fifteen minutes.
Tip: No CRM endpoint handy?
Any request-inspection service works for a first run. It gives you a live URL, and you can watch requests arrive in real time — useful for confirming the shape of the payload before you point it at production.
Contents
- Part one: Build the webhook
- Part two: Test it before it matters
- Part three: Place it in your call flow
Part one: Build the webhook
Step 1: Open the Tools page
From the left navigation, select Tools. Three options appear across the top: Add webhook tool, Add client tool, and Add Integration tool. Choose Add webhook tool — a configuration panel opens from the right side of the screen. Webhook tools connect to any HTTP endpoint you control.
Step 2: Fill in the Configuration card
Four fields define where the request goes and when your agent should send it.
| Field | Example | Notes | |
|---|---|---|---|
1 |
Name | updateCrm |
Letters, numbers and underscores only. Punctuation and spaces are removed as you type. |
2 |
Description | Send the caller's VIN to the CRM. Call this once the caller has given their VIN and confirmed it back correctly. | The most important field on this page. It's the only thing your agent reads when deciding whether to use this tool. Write it as an instruction to a new colleague: what this does, and when to do it. |
3 |
Method | POST |
POST for creating or updating a record; GET for looking something up. |
4 |
URL | https://api.yourcrm.com/v1/vehicles |
Your endpoint. Typing {{ opens a picker for any environment variables you've stored, so the same tool can point at staging or production without editing the URL. |
The card also includes a Response timeout setting (20 seconds by default).
Note: Why the description carries so much weight
Your agent isn't following a script when it decides to call a tool — it's reading your description and judging whether the moment fits. "Send data to CRM" gives it almost nothing to work with. "Call this once the caller has given their VIN and confirmed it back correctly" tells it precisely when to act and when to wait.The agent uses the description as a steering mechanism to check a tool's name and parameters, then using your description, makes a choice to use a tool.
Step 3: Add your authentication header
In the Headers card, choose Add header. Give it a name and pick how the value is supplied. For example:
| Name | Type | Value |
|---|---|---|
Authorization |
Value | Bearer sk_live_•••••••••••• |
Choose the header type based on how the value should be supplied:
| Type | Use it when |
|---|---|
| Value | A straightforward literal, entered here. |
| Secret | The value should be stored in your secret vault rather than shown in the tool. |
| Environment Variable | The value differs between your environments. |
| Dynamic Variable | The value is specific to the individual call. |
Important: One thing to know before you test
The built-in test runner sends Value headers only. Secret, Environment and Dynamic headers are resolved when a call is running, so the test result will list them under "headers not sent." If your endpoint rejects the test with a 401, this is almost always why — switch to a Value header for your first run, then change it back.
Step 4: Define the VIN field
This is where you tell the agent what to collect. In the Query parameters card, choose Add param and fill it in. Each parameter is one field in the outgoing request.
| Setting | Value |
|---|---|
| Data type | String |
| Identifier | VIN |
| Required | Checked |
| Value Type | LLM Prompt |
| Description | The 17-character Vehicle Identification Number the caller provided. Use exactly what they said after they confirmed it back. Never guess or invent a VIN. |
The Description is passed to the LLM and should describe in detail how to extract the data from the transcript.
Tip: Writing descriptions that work
Speech recognition isn't flawless, and VINs are long strings of letters and digits. Naming the length ("17-character") and requiring confirmation ("after they confirmed it back") gives the agent a check it can apply. Adding "never guess" matters more than it looks — without it, a model that missed a character may fill in something plausible.
Choosing a Value Type
| Value Type | What it means |
|---|---|
| LLM Prompt | The agent fills this from the conversation, guided by your Description. Use this for VIN. |
| Constant Value | A fixed value sent every time — useful for tagging the source, e.g. channel: "voice_ai". |
| Dynamic Variable | Pulls from a named call variable — for values already known before the call, like a lead ID from your dialer. |
Note: Where these fields actually land
The card is labeled "Query parameters" for every method, but the request is built according to the method you chose:
POST, PUT, PATCH → sent as the JSON request body →
{"vin": "1HGCM82633A004352"}
GET, DELETE → appended to the URL →?vin=1HGCM82633A004352Since this example uses
POST, VIN arrives in the body. There's no separate body editor to look for.
Step 5: Capture what the CRM sends back (optional)
If your CRM returns a record ID or confirmation number, you can store it and let the agent read it back to the caller. In the Dynamic Variable Assignments card, choose Add:
| Variable Name | JSON Path |
|---|---|
crm_record_id |
data.id |
This saves one field from the CRM's reply for the rest of the call. Your agent can now say "I've logged that — your reference is 48213" instead of ending on silence. It's a small change that makes the integration feel like a conversation rather than a form submission.
Step 6: Save
Select Add tool at the bottom of the panel. Your webhook now appears in the Tools list, ready to test.
Part two: Test it before it matters
Every webhook tool has a built-in test runner. It sends a genuine HTTP request to your endpoint using the configuration you just saved, and shows you exactly what was sent and what came back.
Step 7: Run the test
Open your saved tool and select Test Tool in the panel header. Your parameters appear on the left. Enter a sample VIN (for example, 1HGCM82633A004352) and select Run.
A successful result returns your CRM's response body, for example:
{
"data": {
"id": "48213",
"vin": "1HGCM82633A004352",
"status": "created"
}
}Expanding Raw Request shows the exact request that was dispatched:
POST https://api.yourcrm.com/v1/vehicles
Content-Type: application/json
Authorization: Bearer sk_live_••••••••••••
{ "vin": "1HGCM82633A004352" }The result panel gives you four things: whether it succeeded, the response body your CRM returned, how long it took, and — under Raw Request — the literal request that went out, headers and all.
Tip: Save the response as a mock
Select Save as mock on a successful result and it's stored under Response Mocks. Your team can then rehearse agent behaviour against a realistic CRM reply without sending anything to your live system.
If something doesn't work
| What you see | What it usually means |
|---|---|
| 401 or 403 | Authentication. Check the Raw Request panel — if your header is listed as "not sent," it's a Secret, Environment or Dynamic header. Switch it to Value for testing. |
| Request blocked | The address is private, internal or a loopback. Use a publicly reachable HTTPS endpoint. |
| Timed out | No response inside the window. Confirm the endpoint is up, or raise the response timeout. |
| Your edits weren't included | The test runs your last saved configuration. Save, then test. |
| A field is missing from the test | Only LLM Prompt parameters appear as test inputs. Constant and Dynamic Variable fields are supplied at call time. |
| 400 from your CRM | A real reply, not a failure — your endpoint received the request and objected to its contents. The response body will say why. |
Part three: Place it in your call flow
A tool on its own is a capability. A workflow is where you decide when the agent uses it — what it collects first, what happens when the CRM responds, and what happens when it doesn't.
Step 8: Open the Workflow tab
Go to Agents, open the agent you're configuring, and select the Workflow tab. You'll see a canvas with your call flow on it, starting from a Start step. Every flow begins at Start.
Step 9: Add a step that collects the VIN
Hover the Start step and click the + beneath it. A picker opens listing every step type. Each type does one job in the conversation:
| Step type | What it does |
|---|---|
| Subagent | A conversational step with its own prompt and knowledge. |
| Say | Speaks a scripted or prompted line. |
| Dispatch tool | Executes one or more tools, then branches on the outcome. |
| Update state | Writes values to call-scoped dynamic variables. |
Choose Subagent. In the panel that opens on the right, give the step a name (for example, Collect VIN) and write its instructions:
"Ask the caller for the VIN on their vehicle. Read it back to them character by character and get an explicit confirmation before moving on."
Step 10: Add the Dispatch tool step
Click the + below your new step and choose Dispatch tool. Select the step to open its panel, stay on the Tools tab, and choose Add tool.
Pick updateCrm from the list.
Your flow now reads: Start → Collect VIN → Send to CRM.
The step now shows 1 tool will run here on the canvas. Before you attach anything it reads "No tools attached yet," which makes incomplete steps easy to spot at a glance.
Tip: The other way to attach a tool
Subagent steps have a Tools tab of their own. Attach
updateCrmthere instead and the agent can reach for it at any point during that part of the conversation, rather than at one fixed moment.Use a Dispatch tool step when the tool must run at a specific point — after the VIN is confirmed, before the wrap-up. Attach it to a Subagent when the timing depends on how the conversation goes. Most flows use both.
Step 11: Branch on the outcome
This is what makes the Dispatch tool step worth using. Open its Edges tab and give it two outgoing paths — one for a successful write, one for a failure — then connect each to the step that should follow.
| Path | Next step | Example |
|---|---|---|
| Success | Confirm to caller (Say step) | "All set — your reference is {{crm_record_id}}." |
| Failure | Hand to agent (transfer) | Transfer so nothing is lost. |
Without a failure path, an unreachable CRM leaves the caller in silence. With one, the call keeps moving and the VIN still reaches a human.
Note: a failure path keeps the call moving only when the webhook uses Immediate (or Default) timing with Auto error handling. With Async timing and Silent error handling, a failed webhook can still strand the call even with a failure path — use Immediate timing and Auto error handling for any webhook where losing the caller is not acceptable.
Step 12: Create the VIN variable
So far the VIN travels straight from the conversation into the request. If you want to hold it — reuse it in a spoken line, send it to a second system, check it later in the call — it needs to be a custom variable.
There's no screen where you declare variables up front. You create one by referencing it. Write {{vin}} in any of these places and the variable comes into existence:
- The agent's system prompt
- The agent's first message
- A Subagent step's prompt
- A Say step's text
Typing {{ in any of those fields opens a picker of what's already available, so you can reuse an existing variable instead of accidentally inventing a near-duplicate.
Once referenced, VIN appears under the Variables button in the agent header — the { } icon, with a count badge. Open it to give the variable a type and a test value. Every custom variable you've referenced appears in this panel.
Each variable takes a type — String, Number, Boolean or List — and a test value. A VIN is a String.
Important: Test values are for rehearsal only
The value you enter here is used when you test the agent in development. It is not used on real calls — there, the value either arrives with the call or gets set during the conversation. Treat this field as a stand-in so you can rehearse, not as a default.
Naming rules
| Rule | Examples |
|---|---|
| Must start with a letter |
vin ✓ 2ndVin ✗ _vin ✗ |
| Letters, numbers and underscores only |
vin_confirmed ✓ vin-confirmed ✗ |
Can't begin with system__
|
Reserved for built-in variables |
Names are case-sensitive, so {{vin}} and {{VIN}} are two different variables. Pick one spelling and stay with it.
Step 13: Store the VIN
Referencing the variable creates it; an Update state step is what puts a value in it mid-call. Add one directly after your collection step (for example, named Save VIN), open its General tab, and choose Add update:
| Setting | Value |
|---|---|
| Variable to update | VIN |
| New value | LLM Evaluation |
| Instruction | The VIN the caller provided and confirmed back, exactly as spoken. |
Variable to update lists the custom variables this agent already knows about. If VIN isn't in the list yet, it hasn't been referenced anywhere — go back and put {{vin}} in a prompt first, then return here.
What you can put in a variable
| New value | What it does |
|---|---|
| LLM Evaluation | The agent works the value out from the conversation, following the instruction you write. Use this for the VIN. |
| String / Number | A literal you type — a stage marker, a counter, a fixed code. |
| True / False / Null | Flags: vin_confirmed = True, or clearing a value with Null. |
| Dynamic Variable | Copy another variable's value into this one. |
Tip: Several updates in one step
One Update state step can hold as many rows as you need, and they run in order from top to bottom when the call reaches the step. A later row can read what an earlier row just set — so you can store
vinand then setvin_confirmed = Truein the same step. Drag the rows to change the order.
Step 14: Use it anywhere in the call
Once VIN holds a value, it's available across the whole conversation:
| Where | How |
|---|---|
| Spoken lines and prompts | Write {{vin}} in a Say step or a Subagent prompt — "Just to confirm, that's VIN {{vin}}." |
| The webhook's fields | Set the parameter's Value Type to Dynamic Variable and enter vin as the name. |
| The webhook's URL | Use {{vin}} directly in the URL — e.g. /v1/vehicles/{{vin}}. |
| Request headers | Choose header type Dynamic Variable and name the variable. |
Which approach should you use?
| Situation | Set the parameter to |
|---|---|
| The agent hears the VIN on the call and it's only used once | LLM Prompt — what you configured in Part one. Nothing else to wire. |
| The VIN is known before the call — from your dialer or lead record | Dynamic Variable. The value arrives with the call; no Update state step needed. |
| The VIN is captured on the call and reused — spoken back, sent twice, checked later | Dynamic Variable, with an Update state step to store it first. |
Note: A note on the two directions
Variables move both ways. Update state writes a value you captured during the conversation. Dynamic Variable Assignments — the card from Part one, Step 5 — writes a value your CRM sent back. Between them, anything the call learns can be reused later in the same call.
Step 15: Rehearse the conversation
Open Test chat from the canvas toolbar and talk through the flow as if you were the caller. The canvas highlights the step you're currently on, so you can watch the conversation move through your design and see where the agent decides to reach for the tool.
Note: Test chat is a rehearsal, not a live run
Tool responses in test chat are simulated by default, so you can run the same conversation as many times as you like without writing anything to your CRM. Tool calls are marked accordingly in the transcript.
To verify the request itself reaches your system, use Test Tool from Part two — that one sends a genuine HTTP request.
What you've built
| Setting | Value |
|---|---|
| Tool name | updateCrm |
| Method | POST |
| URL | https://api.yourcrm.com/v1/vehicles |
| Header |
Authorization · type Value |
| Parameter | VIN · String · Required · LLM Prompt |
| Assignment |
crm_record_id ← data.id
|
| Workflow | Start → Collect VIN → Save VIN → Send to CRM → Confirm / Hand off |
| Custom variable | VIN · String · set by an Update state step |
Before you go live
- ☐ Endpoint is publicly reachable over HTTPS
- ☐ Tool saved, then tested — with a green Success result
- ☐ Raw Request shows the payload your CRM expects
- ☐ Tool description states clearly when the agent should call this
- ☐ Parameter description tells the agent how to extract the value, and not to guess
- ☐ The Dispatch tool step has a failure path, not just a success path
- ☐ Every custom variable shows a test value in the Variables panel — a blank one will flag an error
- ☐ Production credentials moved to a Secret or Environment Variable header
- ☐ Flow rehearsed end to end in Test chat
Note: One tool, many uses
Nothing here is specific to VINs. The same six fields carry a policy number, an appointment slot, a callback time or a disposition code — change the parameter and the description, and the pattern holds.
Questions about connecting a specific system? Our Customer Success Team can help!