Webhooks for the chat API

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:

  1. In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settings menu, click Menu.

  2. Go to the Webhooks pane, and then click the Webhooks toggle to the on position.

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

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

  5. Copy and save the token in a secure place.

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

  7. Copy and save the token in a secure place.

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

  1. In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settings menu, click Menu.

  2. Click Rotate Secrets

  3. Click Save.

Generate new secrets

To rotate the secrets so that you have two new secret keys, follow these steps:

  1. In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settings menu, click Menu.

  2. Click Generate to generate a new secondary secret.

  3. Click Rotate Secrets to make the new secondary secret the primary secret.

  4. Click Generate to generate a second new secondary secret that will replace the old primary secret.

  5. Click Save.