Webhooks for the chat API platform

With webhooks, the apps API sends your application a real-time notification each time a relevant event occurs during a chat session—for example, when a chat is created, a message is received, or a chat is transferred or escalated. Use webhooks to react to chat activity as it happens instead of polling the API.

Webhooks are scoped to chat sessions on the apps API. Contact Center AI Platform delivers all supported apps API chat webhook events as HTTP POST requests to a single webhook URL that you configure. There's no per-event subscription.

Before you begin

  • You must be an administrator (or have a role with permission to edit Developer Settings) to configure webhooks.
  • Prepare an endpoint that can receive HTTP POST requests. The webhook URL must use HTTPS.

Turn on webhooks

When you turn on webhooks, Contact Center AI Platform delivers webhook events to your configured URL and the URL and secret fields appear. When webhooks are off, no events are sent.

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.

Configure the webhook URL

  1. In URL, enter your webhook endpoint.
  2. Confirm the endpoint uses HTTPS and can receive POST requests. Contact Center AI Platform sends all supported events to this single URL.

Generate signing secrets

Contact Center AI Platform signs every webhook request so your application can confirm the request came from Contact Center AI Platform. It sends the signature in the X-Signature request header, and the signing timestamp in X-Signature-Timestamp. You can configure up to two signing secrets:

  • Primary secret: The main token used to sign webhook requests.
  • Secondary secret: An optional second token. When a secondary secret is set, Contact Center AI Platform signs each request with both secrets, which lets you rotate secrets without missing events.

Generate each secret separately. To generate a secret, 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.
  3. In the Primary Secret section, click Generate. Click Copy to copy a secret and store it securely. The full secret is shown only right after you generate it. Afterward it is masked.
  4. Optional: In the Secondary Secret section, click Generate. Click Copy to copy a secret and store it securely.
  5. Confirm in the warning dialog. A new secret takes effect immediately, so anything still using a replaced secret fails.

Rotate signing secrets

When a primary secret exists, a Rotate Secrets action becomes available. Rotating your secrets periodically is a security best practice. Because Contact Center AI Platform signs each request with both the primary and secondary secrets, you can rotate without interrupting delivery:

  1. In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settings menu, click Menu.
  2. Make sure both a primary and a secondary secret are set.
  3. Click Rotate Secrets to swap the primary and secondary secrets.
  4. Update your application to verify signatures against the new active secret. During the overlap, Contact Center AI Platform signs each request with both configured secrets, so accept either one and delivery is not interrupted.

Save your configuration

Select Save to apply the webhook's enabled state and URL. Generating or rotating a secret takes effect immediately and does not require a save operation. Contact Center AI Platform begins delivering events after webhooks are enabled and a webhook URL and primary secret are set.

What your application receives

After you enable webhooks, Contact Center AI Platform sends an HTTP POST request for each supported chat event, such as lifecycle changes, participant activity, messages, transfers, escalations, web forms, and dismissal warnings. Each request body is a JSON envelope with event_type, timestamp, chat_id, and an event-specific body.