Skip to main content
The Handover Providers section in the Endpoint settings has been deprecated in 4.97. The removal date is September 2025. We encourage you to try our new Handover Providers interface, which offers greater flexibility for managing your integration with contact centers. For a smooth migration, refer to the migration guide.
The Webhook Endpoint connects your AI Agent to external systems by sending real-time events, such as user or system messages, to a specified callback (webhook) URL. The Endpoint receives POST requests at the Cognigy.AI Endpoint URL, processes them with the assigned Flow, and sends results asynchronously to your webhook URL. If you use Agent Copilot for voice with the Webhook Endpoint, you can switch to a specific Voice Copilot Endpoint. This Endpoint includes all webhook logic, so you don’t need to use a Code Node.

​
Prerequisites

  • Run a web server on your side to receive POST requests from Cognigy.AI at your webhook URL.
  • (Optional) Set up basic authentication for your web server.

​
Generic Endpoint Settings

Learn about the generic Endpoint settings on the following pages:

​
How to Set Up

​
Setup on the Cognigy.AI Side

  1. In the left-side menu of your Project, click Deploy > Endpoints.
  2. On the Endpoints page, click + New Endpoint.
  3. In the New Endpoint section, do the following:
    1. Select the Webhook Endpoint type.
    2. Specify a unique name.
    3. Select a Flow from the list.
  4. Go to the Basic Auth Credentials section and enter the external webhook URL in the Webhook field. This URL is where Cognigy.AI will send output data.
  5. (Optional) If your webhook uses basic authentication, fill in the User and Password fields.
  6. Save changes and go to the Configuration Information section. For sending POST requests to the Cognigy.AI Webhook Endpoint, copy the URL from the Endpoint URL field.

​
Setup on the Third-Party Provider Side

Send a POST request to the Cognigy.AI Webhook Endpoint. Your web server should accept POST requests and process the JSON payload sent by Cognigy.AI. For testing purposes, you can use webhook.site as a temporary web server.
  • cURL
  • Postman
Replace https://<your-endpoint-url> with the Endpoint URL from your Endpoint’s settings.
curl -X POST https://<your-endpoint-url> \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
      "exampleKey": "exampleValue"
    }
  }'
The following JSON response is sent by the Cognigy.AI Webhook Endpoint to your external system. This response contains information about the user, session, and the AI Agent output:
{
   "userId": "user123",
   "sessionId": "session123",
   "AIOutput": {
      "text": "I’d be happy to help. Could you please provide your order number?",
      "data": {},
      "traceId": "endpoint-httpIncomingMessage-83b52cb7-1452-4c2d-a57d-4a81e6adb92c",
      "disableSensitiveLogging": false,
      "source": "bot"
   }
}
ParameterTypeDescription
userIdStringThe ID of the user who sent the original request.
sessionIdStringThe session ID used to track the conversation context.
AIOutput.textStringThe response message generated by the AI Agent.
AIOutput.dataObjectThe message data returned from the Flow.
AIOutput.traceIdStringThe ID used for tracing and debugging purposes.
AIOutput.sourceStringThe message source. Always "bot" for AI Agent replies.
disableSensitiveLoggingBooleanThe flag indicating if logging is disabled. If the value is true, this interaction won’t be logged for privacy or compliance reasons.
1: You must provide at least one of text or data. You can send either, or both. If both are missing or invalid, the REST Endpoint throws an error.
⌘I