Call an AI agent through its Webhook channel
Use the Webhook channel when another application needs to send a request to an AI agent without using a chat widget.
Before you start
Configure and test the agent in Playground.
Choose a trusted calling application and a limited test operation.
Have permission to configure the agent channel.
Obtain the request format and authentication details for that channel.
A channel endpoint is separate from a service deployment entry point. Do not reuse a service payload or a URL copied from another agent.
Enable the channel
Open AI Agent Composer and select the agent.
Open Channels > Webhook.
Complete the available setup controls.
Copy the generated webhook URL.
Store the endpoint in the calling application's protected configuration.
If the generated URL contains a credential, treat the whole URL as confidential. Do not place it in frontend source, public documentation, or shared screenshots.
Prepare the request
Use the HTTP method specified for the generated channel endpoint. The documented channel request uses POST.
Set Content-Type: application/json when sending the documented JSON request.
Use the channel's request example or confirmed input contract.
Map the message and conversation context from the calling application.
Supply the authentication required by the generated setup.
Send one controlled request and retain its timestamp and response.
Do not assume that field names such as message, userId, or sessionId form a universal payload contract. If your setup does not provide a request example, obtain the installed channel's input contract from support before building the integration.
Use a stable conversation identifier only in the way supported by that contract. Do not combine unrelated users into one shared conversation.
Verify the complete result
Confirm that the request reached the intended agent.
Inspect the agent log and any tool execution produced by the request.
Inspect the response received by the caller.
Test how the caller handles an error or delayed response.
Before retrying a request that can change another system, check whether the first attempt already performed the action.
Expected result
The request is associated with the intended agent and conversation, and the caller receives the response defined by the channel's contract. An HTTP acknowledgement alone is not confirmation of every downstream business action.
Troubleshoot
Authentication error: compare the generated setup and the caller's credential configuration.
Invalid request: check the expected field names, types, and content type.
Context is lost or mixed: review the conversation identity mapping.
Timeout: compare caller timeout settings with the agent execution record before retrying.
Duplicate change: inspect the original run and implement the retry/deduplication behavior required by the integration.
When requesting help, include a redacted request, response, timestamp, and execution identifier.
Was this helpful?