Call Webhook
Connect your AI agent to external systems through webhooks for advanced integrations.
Real-Time Integration
Send data to your systems instantly during conversations.
Two-Way Communication
Receive responses from your API to guide the conversation.
Secure & Reliable
HTTPS endpoints with optional authentication headers.
Flexible Data
Send custom variables and receive structured responses.
Overview
The Call Webhook tool empowers your AI agent to interact with external HTTP REST APIs, enabling it to perform a wide range of actions beyond its default capabilities. By configuring this tool, you can integrate your agent with other systems, automate tasks, and enhance conversations with real-time data.
The Call Webhook tool allows your AI agent to:
- Send Data to External APIs: Collect information during a conversation and send it to an external system.
- Receive and Utilize API Responses: Use data returned from the API call to inform or enhance the ongoing conversation.
- Automate Workflows: Trigger actions in other systems, such as creating support tickets, updating records, or retrieving information.
Configuration Parameters
1. Description
A brief explanation of what the tool does. This helps you reference the tool in your instructions.
Example: "Submit Ticket"2. URL
The endpoint URL of the API you want to call.
Example: "https://api.example.com/tickets"3. Method
The HTTP method to use for the request (GET, POST, PUT, DELETE).
Example: "POST"4. Headers
Any custom headers required by the API, such as authentication tokens or content types.
{
"Authorization": "Bearer your_api_token",
"Content-Type": "application/json"
}5. Query String Parameters
Parameters to include in the URL's query string. You can use variables collected from the conversation.
Example: "?email=$email&status=open"6. Body
The request body for POST or PUT requests, formatted as valid JSON. Variables from the conversation can be inserted here.
{
"name": "$name",
"email": "$email",
"message": "$additional_info"
}7. Response Identifiers
Specify keys from the JSON response that the agent can access, using dot notation. This limits the data the agent can use in the conversation.
Example: "ticket_id", "status", "assigned_to.name"How to Use the Call Webhook Tool
Set Up Your Webhook Endpoint
Create an HTTPS endpoint that can receive POST requests:
// Example Node.js/Express endpoint
app.post('/webhook/echowin', async (req, res) => {
const { variables, conversation } = req.body;
// Process the data
const response = await processData(variables);
// Return response for the AI to use
res.json({
success: true,
message: response
});
});Example Scenario: When a customer wants to submit a support ticket.
Configure the Tool in echowin
Add the Call Webhook tool with your configuration:
Example Configuration:
- Description: "Submit Ticket"
- URL: "https://api.example.com/tickets"
- Method: "POST"
- Headers:
{
"Authorization": "Bearer abc123token",
"Content-Type": "application/json"
}- Query String Parameters: (Leave blank if not needed)
- Body:
{
"customer_name": "$name",
"customer_email": "$email",
"issue": "$issue_description"
}Write Instructions for Your Agent
Tell your AI agent when and how to call the webhook:
Instruction Example:
"Collect the caller's name, email, and a description of their issue. Then, use the 'Submit Ticket' tool with variables $name, $email, and $issue_description. Once the ticket is created, inform the caller of their ticket ID."This tells the agent to:
- ✓Collect Information: Gather necessary details from the caller
- ✓Call the Webhook: Use the tool to send data to the external API
- ✓Utilize the Response: Extract specific information from the API response to continue the conversation
Handle the Response
Your webhook can return data that the AI will use:
{
"success": true,
"message": "Appointment confirmed for John at 3 PM",
"additionalData": {
"confirmationNumber": "APT-12345",
"duration": "30 minutes"
}
}Example:
Scenario: Providing real-time stock levels
Agent: "Thank you, $name. Your support ticket has been created. Your ticket ID is $ticket_id. Our team will reach out to you shortly."
Examples
Example 1: Checking Order Status
Scenario:
A customer wants to check the status of their order.
Instructions:
- Ask for the customer's order number.
- Use the "Check Order Status" tool with variable $order_number.
- Inform the customer of their order status using the response from the API.
Configuration:
- Description: "Check Order Status"
- URL: "https://api.example.com/orders/status"
- Method: "GET"
- Query String Parameters: "?order_number=$order_number"
- Response Identifiers: "status", "estimated_delivery"
Agent's Dialogue:
Agent: "May I have your order number to check the status?"
Customer: "It's 12345."
(Calls the webhook and receives the response)
Agent: "Your order is currently '$status' and is expected to be delivered on $estimated_delivery."
Example 2: Scheduling an Appointment
Scenario:
A client wants to schedule an appointment.
Instructions:
- Collect the client's name, preferred date, and service required.
- Use the "Schedule Appointment" tool with variables $name, $date, and $service.
- Confirm the appointment details with the client.
Configuration:
- Description: "Schedule Appointment"
- URL: "https://api.example.com/appointments"
- Method: "POST"
- Body:
{
"client_name": "$name",
"appointment_date": "$date",
"service_type": "$service"
}- Response Identifiers: "confirmation_number", "scheduled_time"
Agent's Dialogue:
Agent: "Could you please provide your name?"
Customer: "Alex Johnson."
Agent: "What date would you like to schedule the appointment?"
Customer: "Next Monday."
Agent: "Which service are you interested in?"
Customer: "Haircut."
(Calls the webhook and receives the response)
Agent: "Your appointment is confirmed for $scheduled_time on $date. Your confirmation number is $confirmation_number."
Advanced Webhook Response Handling
When the API returns a JSON response, you can specify which parts of the response the agent can access using response identifiers.
Example Response:
{
"ticket": {
"id": "TICKET123",
"status": "open",
"assigned_to": {
"name": "Support Agent",
"email": "support@example.com"
}
},
"message": "Ticket created successfully."
}Response Identifiers:
- "ticket.id": Accesses the ticket ID
- "ticket.status": Accesses the status of the ticket
- "ticket.assigned_to.name": Accesses the name of the assigned support agent
By specifying these identifiers, you control what information the agent can use, enhancing security and relevance.
Best Practices
✓ Ensure Valid JSON
The body of POST or PUT requests must be valid JSON. Double-check for syntax errors.
🔒 Secure Data Transmission
Use HTTPS URLs and include necessary authentication headers to protect data.
📝 Variable Naming
Use clear and consistent variable names that match the data being collected.
⚠️ Error Handling
Instruct the agent on what to do if the API call fails or returns an error.
Example Instruction: "If the 'Submit Ticket' tool fails, apologize to the caller and inform them that we will follow up via email."🧪 Testing
Before deploying, test the webhook calls to ensure they work as expected and the agent handles the responses correctly.
Advanced Usage
Using Dynamic Query Strings
You can include variables in the query string to pass data via the URL. Your agent already knows a lot of information from the conversation, things like current date and time, caller's caller ID information (if available), callers phone number (if on a phone call) and more.
Example 1:
- URL: "https://api.example.com/findCustomer"
- Query String Parameters: "?phoneNumber=$phone_number&limit=10"
- Instructions: "When the caller wants to know their account balance, find the customer using variables $phone_number"
Example 2:
- URL: "https://api.example.com/search"
- Query String Parameters: "?query=$search_term&limit=10"
Customizing Headers
Include custom headers for APIs that require them, such as:
"X-Custom-Header": "CustomValue"Handling Different HTTP Methods
- GET: Retrieve data without a body
- POST: Send data to create a new resource
- PUT: Update an existing resource
- DELETE: Remove a resource
Ensure the method matches the API's requirements.
Utilizing API Responses to Enhance Conversations
Use the data returned from the API to make the conversation more informative.
Example:
Scenario: Providing real-time stock levels
Agent: "Let me check the availability of that item."
(Calls the webhook and retrieves the stock level)
Agent: "We currently have $stock_quantity units available."
Technical Details
Supported Adapters
The Call Webhook tool is available for all communication channels:
Response Format
The tool supports JSON responses only. HTML or other formats are not recommended as they may not be processed correctly.
Variable Replacement
Variables in the format $variable_name are automatically replaced with values collected during the conversation. This works in URLs, headers, query parameters, and request bodies.
Error Logging
All webhook calls are logged, including successful responses and errors. This helps with debugging and monitoring your integrations.
Summary
The Call Webhook tool extends your AI agent's functionality by enabling it to interact with external APIs. By carefully configuring the tool and writing clear instructions, you can automate tasks, provide real-time information, and create a more engaging and efficient experience for your customers.
Remember to:
- ✓Define clear purposes and instructions for the agent
- ✓Use variables to capture and pass data effectively
- ✓Securely configure API calls with the correct methods, headers, and body content
- ✓Utilize response identifiers to control the data the agent accesses
- ✓Test thoroughly to ensure seamless operation
By mastering the Call Webhook tool, you unlock a powerful mechanism to integrate your AI agent with the broader digital ecosystem, enhancing both your operations and customer interactions.
You can visit the Tool Usage guide for a brief overview of all the tools.