Webhook - Cognigy Documentation

Updated in 2026.13

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. 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:

Specific Endpoint Settings

API Key Authentication

Use this section to validate incoming requests to this Endpoint using an API key that callers must include in the X-Webhook-Key header.

Parameter	Type	Description
Authentication Method	List	Sets an authentication step for requests sent to this Endpoint. Select one of the options: None — no authentication step. This option is selected by default. API Key — sets API key-based authentication.
Generate API Key	Button	This button appears in the Endpoint API Keys section when you select API Key in Authentication Method. Opens a dialog to generate an Endpoint-specific API key. You can generate multiple Endpoint-specific API keys.

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.

Parameter	Type	Description
User	Text	This parameter is optional. Sets the username to authenticate against when sending requests to the webhook URL.
Password	Text	This parameter is optional. Sets the password to authenticate against when sending requests to the webhook URL.
Webhook	Text	Sets the webhook URL to send requests to.

How to Set Up

Setup on the Cognigy.AI Side

1. Create a Webhook Endpoint

In the left-side menu of your Project, go to Deploy > Endpoints, and click + New Endpoint.
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.
(Optional) In the API Key Authentication section, select API Key from the Authentication Method list. The Endpoint API Keys section appears.
(Optional) In the Endpoint API Keys section, follow these steps:
1. Click + Generate API Key.
2. (Optional) In the dialog box, enter a unique name for your API key and click Generate API Key.
3. (Optional) Click the Key field to copy the generated API key. Make sure you save the API key because it will no longer be visible.
In the Basic Auth Credentials section, enter the external webhook URL in the Webhook field. This URL is where Cognigy.AI will send output data.
(Optional) If your webhook uses basic authentication, fill in the User and Password fields.
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
Postman

Replace https://<your-endpoint-url> with the Endpoint URL from your Endpoint 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"
    }
  }'

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

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

Parameter	Type	Description	Required
userId	String	The ID of the end user.	Yes
sessionId	String	The ID used to track the current session and maintain its state. Generate a new unique ID for each new session. For testing, you can use any string and change it whenever you want to start a new session.	Yes
text	String	The text that the assigned Flow should process.	No, if `data` is specified¹
data	Object	The data that the assigned Flow should process.	No, if `text` is specified¹

With API Key Authentication

cURL
Postman

Replace https://<your-endpoint-url> with the Endpoint URL and <your-api-key> with an active API key from your Endpoint’s settings.

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

Open the Postman collection, select Add a request, then set the request type to POST.
Enter the Endpoint URL as the request URL.
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.
Go to the Body tab, select raw, then select JSON as the format.
Paste the request body:

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

Parameter	Type	Description	Required
userId	String	The ID of the end user.	Yes
sessionId	String	The ID used to track the current session and maintain its state. Generate a new unique ID for each new session. For testing, you can use any string and change it whenever you want to start a new session.	Yes
text	String	The text that the assigned Flow should process.	No, if `data` is specified¹
data	Object	The data that the assigned Flow should process.	No, if `text` is specified¹

2. 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"
   }
}

Parameter	Type	Description
`userId`	String	The ID of the user who sent the original request.
`sessionId`	String	The session ID used to track the conversation context.
`AIOutput.text`	String	The response message generated by the AI Agent.
`AIOutput.data`	Object	The message data returned from the Flow.
`AIOutput.traceId`	String	The ID used for tracing and debugging purposes.
`AIOutput.source`	String	The message source. Always `"bot"` for AI Agent replies.
`disableSensitiveLogging`	Boolean	The flag indicating if logging is disabled. If the value is `true`, this interaction won’t be logged for privacy or compliance reasons.

¹: 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.

​Prerequisites

​Restrictions

​Generic Endpoint Settings

​Specific Endpoint Settings

​How to Set Up

​Setup on the Cognigy.AI Side

​Setup on the Third-Party Provider Side