
POST requests at the Cognigy 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
POSTrequests from Cognigy 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
- Inject and Notify
- Copilot
Endpoint-specific settings
Advanced tab
Basic auth credentials
Use this section to provide the webhook URL and, optionally, credentials Cognigy uses to authenticate outgoing requests to the webhook URL.API key authentication
Use this section to configure how incoming requests to this Endpoint are authenticated.How to set up
Configure in Cognigy
Create a webhook endpoint
Create a webhook endpoint
- In the left-side menu of your project, go to Deploy > Endpoints, and click + New Endpoint.
- In the New Endpoint dialog, select the Webhook endpoint type and click Create endpoint.
- On the Setup tab, configure the following: Endpoint name — enter a unique name. Target type — select an agent or flow from the list. Save changes.
- (Optional) To set up endpoint-specific API authentication, go to the Advanced tab and activate the Require API Key setting in the API Key Authentication section. The Endpoint API keys section appears. Follow these steps:
- Click Generate API Key.
- In the dialog box, enter a unique name for your API key in the Key name field and click Generate API Key.
- Click the Key field to copy the generated API key for later use in the header of requests to the endpoint URL. 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}/apikeysroutes via Cognigy API.
- On the Advanced tab, in the Basic Auth Credentials section, enter the external webhook URL in the Webhook URL field. This URL is where Cognigy sends output data.
- (Optional) If your webhook uses basic authentication, fill in the User and Password fields.
- Save changes. Then, on the Setup tab, in the Integration section, copy the URL from the Endpoint URL field. Use this URL to send
POSTrequests to the Cognigy Webhook endpoint.
Configure in the third-party provider
1. Send a request
1. Send a request
Send a
POST request to the Cognigy Webhook endpoint. Your web server must accept POST requests and process the JSON payload sent by Cognigy. For testing purposes, you can use webhook.site as a temporary web server.No authentication
No authentication
- cURL
- Postman
Replace
https://<your-endpoint-url> with the endpoint URL from the endpoint settings.With API key authentication
With API key authentication
The API key authentication header name depends on your Cognigy version.
For Cognigy 2026.16.0 and later version
For Cognigy 2026.16.0 and later version
Use the
x-cognigy-endpoint-key header. The endpoint also accepts the legacy X-Webhook-Key header for backward compatibility, but x-cognigy-endpoint-key takes precedence if both are provided.- cURL
- Postman
Replace
https://<your-endpoint-url> with the endpoint URL and <your-api-key> with an active API key from the endpoint settings.For Cognigy 2026.13 to 2026.15
For Cognigy 2026.13 to 2026.15
- cURL
- Postman
Replace
https://<your-endpoint-url> with the endpoint URL and <your-api-key> with an active API key from the endpoint settings.2. Get a response
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 agent output:
More information
1: You must provide at least one of
text or data. You can send either, or both. If both are missing or invalid, the Webhook endpoint throws an error.