> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/webhooks/overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Webhooks

For Messaging with Zendesk Chat handoffs, review the [private-mode conversation-end timing](/messaging/introduction/reporting-differences-from-the-chat-sdk#zendesk-chat-in-private-mode-when-the-tab-closes). Closing a tab can delay the `v1.conversation.ended` webhook until the conversation times out.

Webhooks notify your systems in real time about events occurring within Ada. By configuring webhook endpoints, you can integrate Ada with your existing systems to automate workflows and enhance operational efficiency.

Webhook endpoints can be managed through the Ada dashboard or programmatically through the [Webhook management API](#webhook-management-api).

Download full OpenAPI spec

**Key features:**

* Secure communication using HTTPS
* Automatic [retries](#retry-policy) up to a week
* Comprehensive logging for monitoring delivery and failures
* Message [replay](#message-replay) to recover from downtime or missed events
* Programmatic management through the Webhooks API

To ensure reliable delivery, webhooks require a 2xx HTTP status response within 15 seconds. If no response is received, retries are automatically initiated based on an exponential backoff [retry policy](#retry-policy).

## Supported events

Ada supports event notifications that enable you to track specific user actions and updates. The following events are currently supported:

| Event                                                                              | Initiated when                                                                                                  |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`v1.end_user.created`](/reference/end-users/end-user-created-webhook)             | A new user is created through any of Ada's supported channels                                                   |
| [`v1.end_user.updated`](/reference/end-users/end-user-updated-webhook)             | A value on the end user's profile changes                                                                       |
| [`v1.conversation.created`](/reference/conversations/conversation-created-webhook) | A new conversation is created for a supported channel                                                           |
| [`v1.conversation.ended`](/reference/conversations/conversation-ended-webhook)     | A conversation ends—either via `POST /v2/conversations/{conversation_id}/end/` or when a Voice call disconnects |
| [`v1.conversation.message`](/reference/conversations/conversation-message-webhook) | A new message is added to a supported channel                                                                   |
| [`v1.audit_log.emitted`](/reference/audit-log/audit-log-webhook)                   | A configuration change is recorded in the Audit log                                                             |

## Webhook management API

Webhook endpoints can be managed programmatically using the Webhooks API. This is useful for automating webhook configuration across environments or integrating webhook setup into deployment pipelines.

The API supports:

* Creating, listing, updating, and deleting webhook endpoints
* Retrieving and rotating signing secrets
* Listing available event types

**Authentication:** Requires an [Ada API key](/reference/introduction/authentication).

**Webhook identifiers:** Each webhook has a unique ID (for example, `ep_2bxE8VNtkWEMpJrMJv74FlSQmqP`). Use this ID with the get, update, delete, and secret management endpoints.

> **Info**
>
> Webhooks created via the API are identical to those created in the dashboard. They appear in both interfaces and share the same delivery infrastructure.

For endpoint details, see the **Webhooks** API reference in the sidebar.

## Adding an endpoint via dashboard

To begin receiving webhooks through the dashboard:

1. Navigate to **Config > PLATFORM > Webhooks** in your dashboard
2. Click **Add Endpoint**
3. **Provide a URL**: Specify a URL that your system controls
4. **Select Event Types**: Choose the events you wish to subscribe to
5. Click **Create**

**Best practice**: Start with all event types enabled for initial testing and narrow down to relevant types for production to minimize extraneous messages.

## Channel filtering

Webhook endpoints can be scoped to a subset of events using Svix channel tags. This is useful when a single AI Agent fans out to multiple integrations and each integration only needs events relevant to its scope.

Ada tags outgoing webhook events with the following channel values:

| Event source                                                                       | Channel tag(s) applied                                                   |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Conversations API custom channel                                                   | The custom channel's ID (for example, `5df263b7db5a7e6ea03fae9b`)        |
| Handoff integration                                                                | The handoff integration name (for example, `salesforce`, `zendesk_chat`) |
| Conversations API conversation in an active handoff                                | Both the custom channel ID and the handoff integration name              |
| A text message the AI Agent sends during a native Voice call over your SMS channel | The SMS channel's ID                                                     |
| Any other event on Native Chat, Voice, or Email without a handoff                  | None                                                                     |

> **Note**
>
> Ada tags one event type with the SMS channel's ID. That event is the `v1.conversation.message` event for each text message the AI Agent sends during a native Voice call. Ada does not publish the caller's reply as an event. The call stays on the native Voice channel, and its other events carry no tag.
>
> Ada tags the event only when all of these conditions are true:
>
> * **Allow AI Agent to send and receive SMS** is enabled.
> * Your AI Agent has an SMS channel.
> * **Use your own SMS channel** is turned on in **Config > CHANNELS > Voice > Configuration**.
>
> See [Relaying voice texts through your own SMS provider](/reference/conversations/developer-guides/relaying-voice-texts-through-your-own-sms-provider).

To filter an endpoint by channel:

1. Open the endpoint in **Config > PLATFORM > Webhooks**.
2. In the endpoint's **Channels** field, add one or more channel values.
3. Save the endpoint. The endpoint receives only events tagged with at least one of the listed channels.

> **Tip**
>
> Filtering is applied by Svix before delivery, so unmatched events never reach the endpoint. This reduces inbound traffic and removes the need for application-side filtering.

**Example.** A Conversations API integration with a custom channel ID of `5df263b7db5a7e6ea03fae9b` can scope its endpoint to that single channel by adding `5df263b7db5a7e6ea03fae9b` to the **Channels** field. The filter excludes events from other custom channels. It also excludes native chat, voice, and email events. If the **Channels** field holds your SMS channel's ID, the endpoint also receives the text messages the AI Agent sends during a native Voice call. Each arrives as a `v1.conversation.message` event. The other events of that call stay excluded.

## Signing secrets

Each webhook endpoint has a unique signing secret that can be used to verify that incoming payloads are authentic. You can retrieve or rotate the signing secret through the API or the dashboard.

## Adding custom headers to an endpoint

After creating an endpoint, you can configure custom headers that will be included with every webhook delivery sent to that endpoint.

> **Tip**
>
> Custom headers are configured at the endpoint level, not per individual webhook message.

To add a custom header to an existing endpoint:

1. Navigate to **Config > PLATFORM > Webhooks** in your dashboard
2. Select the endpoint you want to update
3. Open the **Advanced** tab
4. In the **Custom Headers** section, add a header using a key–value pair
5. Save your changes

### How custom headers work

* Once configured, the custom header will be included on all webhook requests delivered to that endpoint
* Custom headers are applied per endpoint, not per event or message
  > **Info**
  >
  > Message-level custom headers are **not currently supported**.

## Retry policy

Ada employs an exponential backoff retry mechanism to ensure reliable webhook delivery. This mechanism is triggered when an endpoint fails to respond with a 2xx HTTP status code. Below is the retry schedule:

**Retry schedule:**

1. Immediate retry after failure
2. 5 seconds later
3. 5 minutes later
4. 30 minutes later
5. 2 hours later
6. 5 hours later
7. 10 hours later (repeated for up to 2 attempts)

**Failure handling:**

* If all attempts to deliver to an endpoint fail for **one week**, the endpoint will be automatically disabled
* Manually re-enable endpoints through the Webhooks UI when they are ready to resume operations

# IP allowlist

Webhook deliveries originate from a dedicated infrastructure, not directly from Ada's servers. If your systems use IP allowlisting or firewall restrictions, you must allowlist the appropriate [source IP ranges](https://docs.svix.com/receiving/source-ips) to receive webhook events.

## Why this matters

Blocking these IPs will prevent your endpoint from receiving webhook requests, even if the endpoint is correctly configured.

## Regions

Source IPs are region-specific. Your region is determined by your AI Agent's domain:

* **US region:** Agents on `*.ada.support` domains
* **EU region:** Agents on `*.ada-eu.support` domains

## What you need to do

If IP allowlisting is enabled on your webhook receiver, review the [source IP addresses](https://docs.svix.com/receiving/source-ips) for your region and add the applicable IPs to your firewall or allowlist configuration.

# Testing webhooks

Testing ensures that your webhook endpoints are functioning as intended. Tools such as [ngrok](https://ngrok.com/) or [localtunnel](https://github.com/localtunnel/localtunnel) can simulate real-world scenarios by exposing a local server for testing. Alternatively, you can use Ada's webhooks UI with [Svix Play](https://play.svix.com/) for a quick and easy setup.

### Svix Play

If you don't have a URL ready or your service isn't prepared to receive events, simply press the **Use Svix Play** button in the webhooks UI. This will generate a unique URL for testing purposes.

* Events will be sent to your Svix Play URL and automatically logged in Message Attempts section of the webhooks UI.

> **Warning**
>
> Svix Play is strictly for testing and should not be used in production environments.

## Message replay

Replaying messages can be crucial in several scenarios:

* **Service downtime**: If your service experiences downtime, you can recover missed messages
* **Misconfigured endpoint**: If your endpoint was misconfigured, replaying ensures no data is lost
* **Single event replay**: To replay a single event, go to the log section, use the menu next to the message, and select the "resend" option to send the message to your endpoint again

### Resend message

To resend a single event, simply click **Resend** in the options menu from the log section, and the message will be sent to your endpoint once more.

### Recovering from service outage

If you need to recover from a service outage and replay all events since a specific time, navigate to the Endpoint page. On an endpoint's details page, select **Options > Recover Failed Messages**. From there, you can choose a time window to recover from.

## Rate limits

All Webhooks API endpoints adhere to the [global rate limits](/reference/introduction/limits).

## Troubleshooting common issues

* **Response timeout**: Ensure your endpoint processes messages within the allotted 15-second window. Offload complex workflows to asynchronous processes to avoid timeouts
* **Incorrect response codes**: Always respond with a `2xx` HTTP status code to indicate successful processing

> Overview