How to Set Up Inbound Webhook Triggers for Managed Agents
Inbound Webhook triggers let external applications start Chat To Clients CRM Managed Agents automatically. When an application sends data to a webhook URL, the agent receives that information and follows its configured instructions. You can connect order systems, payment tools, forms, and other applications without creating a separate Workflow or manually mapping every field. This article explains how to set up, secure, test, and monitor an Inbound Webhook trigger.
TABLE OF CONTENTS
- What is an Inbound Webhook Trigger for Managed Agents?
- Key Benefits of Inbound Webhook Triggers
- How Inbound Webhook Triggers Work
- Supported Request Data and Limits
- Securing Webhook Requests
- Managing Multiple Webhook Triggers
- Monitoring Webhook Activity
- Understanding Webhook Responses and Errors
- How to Set Up an Inbound Webhook Trigger for Managed Agents
- Frequently Asked Questions
- Related Articles
What is an Inbound Webhook Trigger for Managed Agents?
An Inbound Webhook trigger starts a Managed Agent when an external application sends an HTTP POST request to its unique webhook URL.
For example, when a customer places an order, an online store can send the order information to the agent. The agent can then find the customer's contact and create a note with the order details.
The agent reads the incoming data based on its instructions.
Note: Managed Agent Inbound Webhooks are different from Workflow Inbound Webhooks. Managed Agent webhooks start an agent directly and do not require Workflow field mapping.
Key Benefits of Inbound Webhook Triggers
Inbound Webhook triggers help Managed Agents respond to events happening in other applications without manual intervention.
Direct Integration: Connect external applications without creating a separate Workflow.
Automatic Data Processing: Let the agent interpret incoming fields using its instructions.
Flexible Formats: Receive JSON, form data, XML, plain text, and multipart requests.
Multiple Triggers: Use separate webhook URLs for different events.
Optional Security: Verify incoming requests using a shared token.
Duplicate Protection: Prevent supported repeated requests from starting duplicate runs.
Execution Tracking: Review webhook activity and agent results.
How Inbound Webhook Triggers Work
Each Inbound Webhook trigger has a unique URL. When an external application sends information to that URL, Chat To Clients CRM starts the published Managed Agent.
Here's how it works:
An external application sends an HTTP POST request.
Chat To Clients CRM verifies the request, if verification is enabled.
The agent receives the request data as its initial input.
The agent processes the data using its instructions.
The execution appears in the agent's Activity Feed.
For example, an online store can send new order details, allowing the agent to identify the customer and create an internal note.
Important: The webhook works only when the agent is published. Unpublishing the agent or removing the trigger disables its URL.
Supported Request Data and Limits
Inbound Webhooks support several request formats, allowing Managed Agents to receive information from different external applications.
Supported formats include JSON, form data, XML, plain text, and multipart requests.
The agent can read the request body, query parameters, and permitted headers.
For example, you can instruct the agent to find the customer's email address in customer.email.
| Setting | Limit or behavior |
|---|---|
| Request method | POST |
| Maximum payload | 256 KB |
| Request rate | Up to 60 requests per minute |
| Successful acceptance | HTTP 202 with a run ID |
Note: HTTP 202 means the request was accepted for processing, not that the agent has finished. The scope of the request-rate limit should be verified before configuring high-volume integrations.
Securing Webhook Requests
Shared-token verification helps prevent unauthorized applications from starting your Managed Agent.
When enabled, the sending application must include the token in either of these request headers:
X-Webhook-TokenAuthorization: Bearer
Requests without a valid required token are rejected with HTTP 401.
The token is shown only when generated. You can regenerate it from the webhook settings if needed.
Important: Keep your webhook URL and token private. If you regenerate the token, update the token in the external application.
Managing Multiple Webhook Triggers
A Managed Agent can have multiple Inbound Webhook triggers, each with its own name, URL, and message. This allows one agent to handle different events.
For example:
New Order: Process a new purchase.
Refund Requested: Review a refund request.
Give each trigger a clear name and describe how the agent should handle its incoming data.
Monitoring Webhook Activity
The Activity Feed helps you confirm that requests were received and review what the agent did with them.
To review a webhook execution:
Go to AI Agents → Agent Studio.
Open the Managed Agent.
Select Activity.
Find a Webhook received entry.
Open the execution to review the request and agent output.
Screenshot description: Show the incoming webhook message, execution timeline, and agent output. Use synthetic data and hide sensitive information.
Understanding Webhook Responses and Errors
Webhook response codes help you identify whether a request was accepted or why it failed.
| Status | Meaning | What to check |
|---|---|---|
| 202 | Request accepted | Review the run in Activity |
| 401 | Authentication failed | Check the token and request header |
| 404 | Webhook not found | Verify the webhook URL |
| 410 | Webhook unavailable | Check whether the trigger or agent is active |
| 413 | Request too large | Reduce the payload size |
| 415 | Unsupported format | Check the request format and Content-Type |
| 429 | Too many requests | Reduce the request rate and follow Retry-After |
Duplicate requests: If an external application retries a delivery, Chat To Clients CRM can recognize supported duplicates using an idempotency key, webhook event ID, or matching request body within a short period. Instead of creating another execution, it returns the original run.
How to Set Up an Inbound Webhook Trigger for Managed Agents
You can connect an external application to your Managed Agent by adding an Inbound Webhook trigger, configuring its instructions, and testing the connection.
The following example uses an online store that sends new order details to an agent.
Step 1: Open a Managed Agent
Go to AI Agents → Agent Studio.
Open an existing Managed Agent or create a new one.
Open the agent editor.
Step 2: Add the Inbound Webhook Trigger
Find Triggers and click Add trigger.
Select Inbound webhook.
Name the trigger, such as New Order.
Step 3: Configure the Agent's Instructions
Tell the AI builder how to use the incoming data.
For example:
"When a new order arrives through the webhook, find the customer using their email address and create an internal note containing the order details."
If the external application uses specific field names, include them in the instructions, such as customer.email.
Step 4: Configure Webhook Security
Open the Inbound webhook trigger settings.
Under Verification, select Shared token header if authentication is required.
Generate and securely copy the token.
Save the trigger settings.
The sending application must include the token in its request headers when verification is enabled.
Step 5: Publish and Copy the Webhook URL
Save the agent and trigger configuration.
Review the agent's instructions.
Publish the Managed Agent.
Open the Inbound webhook settings.
Click Copy beside Webhook URL.
The URL is generated when the configuration is saved and becomes active when the agent is published.
Step 6: Connect the External Application
In your external application:
Open its webhook or HTTP request settings.
Select POST.
Paste the Managed Agent's webhook URL.
Configure the data to send.
Add the shared token to the request headers if verification is enabled.
Save the configuration.
The exact steps depend on the external application.
Step 7: Test the Webhook
Send a test request from the external application.
Return to the Inbound webhook settings.
Check Last request.
Open the linked execution, if available.
Important: Use synthetic data or a test contact when testing agents that can send messages or update CRM records.
Step 8: Review the Execution
Open the Managed Agent's Activity tab.
Select the Webhook received entry.
Check the incoming request and agent output.
Adjust the agent's instructions if needed.
Frequently Asked Questions
Q: Do I need a Workflow to use an Inbound Webhook with a Managed Agent?
A: No. The trigger starts a Managed Agent directly.
Q: Does the external application have to send JSON?
A: No. JSON, form data, XML, plain text, and multipart requests are supported.
Q: Can an agent have more than one webhook URL?
A: Yes. Each Inbound Webhook trigger has its own URL.
Q: Is shared-token verification required?
A: No. It is optional but recommended when the sending application supports authentication headers.
Q: What if I lose my shared token?
A: Regenerate it in the trigger settings and update the external application.
Q: What happens if the same request is sent twice?
A: Supported duplicate requests are recognized and return the original run instead of starting another execution.
Q: Does HTTP 202 mean the agent finished its work?
A: No. It means the request was accepted and queued for processing.
Q: What happens if I unpublish the agent?
A: Its webhook URL stops accepting requests.
Q: Where can I see the data received through the webhook?
A: Open the agent's Activity Feed and select the corresponding Webhook received execution.