Webhook - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

As of Cognigy.AI 4.97.0, the Handover Providers section in the Endpoint settings is deprecated. From Cognigy.AI 2026.4 on, the Handover Settings section in the Endpoint settings is in read-only mode. You can’t use this section to configure new handover providers. You can still view configured handover provider settings, but you can’t change them. To configure handover providers, use the 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. Additionally, you can configure API key-based authentication for requests to this Endpoint. 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.

POST Request

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

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

Restrictions

• Snapshots and Packages don’t support API keys generated in this Endpoint. If you export a Webhook Endpoint that includes an API key, generate a new API key in the target Project. Then update your code to include the new API key.

Generic Endpoint Settings

Learn about the generic Endpoint settings on the following pages:

• Endpoints Overview
• NLU Connectors
• Data Protection & Analytics
• Real-Time Translation Settings
• Handover Settings
• Inject and Notify
• Copilot

Specific Endpoint Settings

API Key Authentication

Use this section to configure how incoming requests to this Endpoint are authenticated.

Basic Auth Credentials

Use this section to provide the webhook URL and, optionally, credentials Cognigy.AI uses to authenticate outgoing requests to the webhook URL.

How to Set Up

Setup on the Cognigy.AI Side

1. Create a Webhook Endpoint
   1. In the left-side menu of your Project, go to Deploy > Endpoints, and click + New Endpoint.
   2. 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. (Optional) To set up Endpoint-specific API authentication, select API Key from the Authentication Method list in the API Key Authentication section. The Endpoint API Keys section appears. Follow these steps:
         1. Click + Generate API Key.
         2. In the dialog box, enter a unique name for your API key and click Generate API Key.
         3. Click the Key field to copy the generated API key for later use in the X-Webhook-Key header. Save the API key because you can’t retrieve it after closing the dialog. Alternatively, you can create and manage API keys for this Endpoint using the /v2.0/endpoints/{endpointId}/apikeys routes via Cognigy API.
      5. In the Basic Auth Credentials section, enter the external webhook URL in the Webhook field. This URL is where Cognigy.AI sends output data.
      6. (Optional) If your webhook uses basic authentication, fill in the User and Password fields.
      7. 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

1. Send a Request

Send a POST request to the Cognigy.AI Webhook Endpoint. Your web server must 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.

No Authentication

• cURL

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"
    }
  }'

1. Open the Postman collection, select Add a request, then set the request type to POST.
2. Enter the Endpoint URL as the request URL.
3. Go to the Headers tab and add Content-Type: application/json.
4. Go to the Body tab, select raw, then select JSON as the format.
5. Paste the request body:

{
  "userId": "user123",
  "sessionId": "session123",
  "text": "Hello, I need help with my order",
  "data": {
    "exampleKey": "exampleValue"
  }
}

With API Key Authentication

• cURL

curl -X POST https://<your-endpoint-url> \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Key: <your-api-key>" \
  -d '{
    "userId": "user123",
    "sessionId": "session123",
    "text": "Hello, I need help with my order",
    "data": {
      "exampleKey": "exampleValue"
    }
  }'

1. Open the Postman collection, select Add a request, then set the request type to POST.
2. Enter the Endpoint URL as the request URL.
3. Go to the Headers tab and configure:
   • Content-Type — select application/json
   • X-Webhook-Key — the API key you generated in the API Key Authentication section.
4. Go to the Body tab, select raw, then select JSON as the format.
5. Paste the request body:

{
  "userId": "user123",
  "sessionId": "session123",
  "text": "Hello, I need help with my order",
  "data": {
    "exampleKey": "exampleValue"
  }
}

Get a Response

The Webhook Endpoint sends the following JSON response 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"
   }
}