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:

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.

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.

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.

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.

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.

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