Stay organized with collections
Save and categorize content based on your preferences.
Webhooks provide a way for external applications to receive real-time
notifications when certain events occur in the platform.
To use webhooks, you must turn them on and generate tokens. By using two
separate secrets for a single webhook URL, you add an extra layer of security.
If one secret becomes compromised or needs to be rotated for any reason you can
update and rotate the secrets without interrupting the webhook service or
jeopardizing data security.
Turn on webhooks
To turn on webhooks, follow these steps:
In the CCAI Platform portal, click Settings > Developer Settings.
If you don't see the Settings menu, click menuMenu.
Go to the Webhooks pane, and then click the Webhooks toggle to the
on position.
For URL, enter a webhook URL. This URL is the endpoint that receives
real-time notifications. Be sure that this webhook can receive HTTP requests.
Click Generate. This generates the primary secret, which is the main
security token used to authenticate and validate incoming webhook payloads.
It acts as the primary means for securing the webhook communication.
Copy and save the token in a secure place.
Generate a secondary secret. The secondary secret serves as the backup or
failover security token. It is provided as an additional security measure to
enhance the reliability and availability of webhook notifications. If for
any reason, the primary secret is compromised or if there are issues with its
usage, the secondary secret can take over and continue ensuring communication.
Copy and save the token in a secure place.
Click Save.
Rotate secrets
As a security best practices, rotate Webhook secrets
periodically. This process involves generating new secret keys for both the
primary and secondary webhooks and updating them in your application to continue
receiving notifications seamlessly.
After the initial set up for webhooks, you can't generate a new primary secret
directly, however you can generate a new secondary secret and rotate the secrets
to change them.
To rotate secrets, follow these steps:
In the CCAI Platform portal, click Settings > Developer Settings.
If you don't see the Settings menu, click menuMenu.
Click Rotate Secrets
Click Save.
Generate new secrets
To rotate the secrets so that you have two new secret keys, follow these steps:
In the CCAI Platform portal, click Settings > Developer Settings.
If you don't see the Settings menu, click menuMenu.
Click Generate to generate a new secondary secret.
Click Rotate Secrets to make the new secondary secret the primary secret.
Click Generate to generate a second new secondary secret that will
replace the old primary secret.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Webhooks for the chat API\n\nWebhooks provide a way for external applications to receive real-time\nnotifications when certain events occur in the platform.\n\nTo use webhooks, you must turn them on and generate tokens. By using two\nseparate secrets for a single webhook URL, you add an extra layer of security.\nIf one secret becomes compromised or needs to be rotated for any reason you can\nupdate and rotate the secrets without interrupting the webhook service or\njeopardizing data security.\n\nTurn on webhooks\n----------------\n\nTo turn on webhooks, follow these steps:\n\n1. In the CCAI Platform portal, click **Settings \\\u003e Developer Settings** .\n If you don't see the **Settings** menu, click menu **Menu**.\n\n2. Go to the **Webhooks** pane, and then click the **Webhooks** toggle to the\n on position.\n\n3. For **URL**, enter a webhook URL. This URL is the endpoint that receives\n real-time notifications. Be sure that this webhook can receive HTTP requests.\n\n4. Click **Generate**. This generates the primary secret, which is the main\n security token used to authenticate and validate incoming webhook payloads.\n It acts as the primary means for securing the webhook communication.\n\n5. Copy and save the token in a secure place.\n\n6. Generate a secondary secret. The secondary secret serves as the backup or\n failover security token. It is provided as an additional security measure to\n enhance the reliability and availability of webhook notifications. If for\n any reason, the primary secret is compromised or if there are issues with its\n usage, the secondary secret can take over and continue ensuring communication.\n\n7. Copy and save the token in a secure place.\n\n8. Click **Save**.\n\nRotate secrets\n--------------\n\nAs a security best practices, rotate Webhook secrets\nperiodically. This process involves generating new secret keys for both the\nprimary and secondary webhooks and updating them in your application to continue\nreceiving notifications seamlessly.\n\nAfter the initial set up for webhooks, you can't generate a new primary secret\ndirectly, however you can generate a new secondary secret and rotate the secrets\nto change them.\n\nTo rotate secrets, follow these steps:\n\n1. In the CCAI Platform portal, click **Settings \\\u003e Developer Settings** .\n If you don't see the **Settings** menu, click menu **Menu**.\n\n2. Click **Rotate Secrets**\n\n3. Click **Save**.\n\nGenerate new secrets\n--------------------\n\nTo rotate the secrets so that you have two new secret keys, follow these steps:\n\n1. In the CCAI Platform portal, click **Settings \\\u003e Developer Settings** .\n If you don't see the **Settings** menu, click menu **Menu**.\n\n2. Click **Generate** to generate a new secondary secret.\n\n3. Click **Rotate Secrets** to make the new secondary secret the primary secret.\n\n4. Click **Generate** to generate a second new secondary secret that will\n replace the old primary secret.\n\n5. Click **Save**."]]
