For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Login
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
  • Introduction
    • Overview
    • Authentication
    • Versioning
    • Limits
    • Pagination
    • Errors
    • Migrate to V2
    • Changelog
  • Knowledge
    • Overview
    • Sources
    • Articles
    • Tags
  • End Users
    • Overview
    • Getting started
    • Developer guide
  • Integrations
    • Overview
    • Getting started
  • Conversations
    • Overview
    • Getting started
  • Webhooks
    • Overview
  • Data Compliance
    • Overview
  • Data Export
    • Overview
    • Getting started
    • Conversations
    • Messages
Login
LogoLogo
On this page
  • Supported events
  • Webhook management API
  • Adding an endpoint via dashboard
  • Channel filtering
  • Signing secrets
  • Adding custom headers to an endpoint
  • How custom headers work
  • Retry policy
  • IP allowlist
  • Why this matters
  • Regions
  • What you need to do
  • Testing webhooks
  • Svix Play
  • Message replay
  • Resend message
  • Recovering from service outage
  • Rate limits
  • Troubleshooting common issues
Webhooks

Webhooks

Overview
Previous

List webhooks

Next
Built with

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.

Key features:

  • Secure communication using HTTPS
  • Automatic retries up to a week
  • Comprehensive logging for monitoring delivery and failures
  • 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.

Supported events

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

EventInitiated when
v1.end_user.createdA new user is created through any of Ada’s supported channels
v1.end_user.updatedA value on the end user’s profile changes
v1.conversation.createdA new conversation is created for a supported channel
v1.conversation.endedA conversation ends—either via POST /v2/conversations/{conversation_id}/end/ or when a Voice call disconnects
v1.conversation.messageA new message is added to a supported channel

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.

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

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 sourceChannel tag(s) applied
Conversations API custom channelThe custom channel’s ID (for example, 5df263b7db5a7e6ea03fae9b)
Handoff integrationThe handoff integration name (for example, salesforce, zendesk_chat)
Conversations API conversation in an active handoffBoth the custom channel ID and the handoff integration name
Native Chat, Voice, or Email without a handoffNone

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.
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. Events from native chat, voice, or other custom channels are excluded automatically.

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.

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
    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 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 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 or localtunnel can simulate real-world scenarios by exposing a local server for testing. Alternatively, you can use Ada’s webhooks UI with Svix Play 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.

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.

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