Skip to main content

​
Introduction

A webhook step sends an outbound API request to an external service during a live call. Use it to retrieve data, trigger workflows, or pass information to third-party systems. Webhook steps live inside a Pathway, the kind of pathway you lay out yourself in the agent builder. To add one:
  1. Open your agent and, under Pathways, open an existing Pathway or click New pathway and choose Pathway.
  2. The graph column becomes the canvas for that pathway.
  3. Add a webhook step to the canvas and connect it to the steps around it.
See Extend the agent with pathways for how pathways fit into an agent.
Webhook step or webhook tool? A webhook step runs when the conversation reaches it in a pathway, in a fixed order you can point to. A webhook tool is tagged into a prompt with @, and the agent decides when to call it. Use a step when the request must happen at a guaranteed point in the flow. Use a tool when the agent should call it whenever the conversation needs it.

​
Step configuration

​
1. Extract call info into variables

When enabled, the step extracts variables from the conversation so far, based on each variable’s name and description, before the request is sent. For example, a step could extract user_name and a True or False user_interested from a conversation about the caller’s availability. You can then use them in the request body:

​
2. Webhook configuration

This section defines how the outbound request is sent.

​
Request type

Choose the HTTP method (GET, POST, and so on).

​
URL

The endpoint of the external service. The URL may include query parameters:
Query parameters can use variables captured earlier in the call:

​
Authorization and headers

Authorization can be configured as:
  • None: no Authorization header is included.
  • Bearer: authenticate with a bearer token. Enter only the raw token. The Bearer prefix is added for you.
  • Basic: authenticate with a username and password in base64 format.
Headers and auth tokens can reference secrets so credentials stay out of plaintext.

​
Body

Compose a payload for the request. The body can include static values or variables captured earlier in the call:
You also have access to Bland’s built-in variables:
  • {{phone_number}}: always the other party’s number
  • {{timezone}}: the timezone of the other party’s {{phone_number}} (for example, America/New_York)
  • {{country}}: the country code (for example, US)
  • {{state}}: the state or province’s abbreviation (for example, CA for California)
  • {{city}}: the full city name, capitalized
  • {{zip}}: the zip code
  • {{call_id}}: the unique ID of the current call
  • {{now}}: current time in the call’s timezone
  • {{now_utc}}: current time in UTC format
  • {{from}}: the outbound number in E.164 format
  • {{to}}: the inbound number in E.164 format
  • {{short_from}}: the outbound number with the country code removed
  • {{short_to}}: the inbound number with the country code removed

​
3. Advanced settings

  • Timeout: maximum wait time before the request is considered failed
  • Retries: number of retry attempts on failure
  • Reroute through server: helps prevent CORS issues. Disable it only if rerouted requests cause problems.
  • Test API Request: sends a live test request and shows the raw response or errors

​
Response data mapping

If the webhook returns a JSON response, you can extract values into variables for later steps:
  • Enable Response Data
  • For each value to extract:
    • Define a Variable Name (a single string, like user_id)
    • Provide the JSON Path (like $.data.id)
    • Optionally add a Description for more context

​
Routing after the response

Set where the conversation goes next based on the webhook result. For example, route to one step if the response status is 200 and another if it is 500.
Every webhook step needs a route for the default API Request Completion before you save it for the first time.
Routing on response HTTP codes only works when Response Data is enabled. With it disabled, the step does not wait for a response.
Routes are evaluated from top to bottom, and each true condition overwrites the previous result:
  • If the first route points to step “a” and evaluates to true, the next step is set to “a”.
  • If the second route points to step “b” and also evaluates to true, the next step becomes “b”.
After all conditions are evaluated, the last true condition decides where the conversation goes.
If a route uses API Request Completion (Default) and it evaluates to true, it takes precedence over all other conditions.

​
Speech during the webhook

You can have the agent speak while the request is processing:
  • It avoids awkward silences during longer requests
  • Example: “One moment while I look up your information.”
  • The speech can be static text or generated from a prompt
Docs for agents: llms.txt