Webhooks

Overview

Every agent in Tuner can have one webhook URL, whatever its provider. Set it in Agent Settings > Webhooks, and Tuner sends events to it as they happen.

Event	When it’s sent	Available for
`call.analyzed`	Tuner finishes analyzing a call for the first time	All providers
`alert.fired`	A real-time alert triggers (with the Webhook channel enabled)	All providers
`call.received`	Tuner receives Retell’s `call_analyzed` event or Vapi’s `end-of-call-report` message, and forwards it	Vapi and Retell only

Setup

Open your agent's webhook settings

Select the agent in the sidebar, open Agent Settings and go to the Webhooks tab.

Enter your webhook URL

In URL, enter the endpoint that should receive events, for example your n8n, Zapier or custom server endpoint. See URL requirements.

Save

Click Save. Tuner starts sending events to your URL.

URL requirements

Tuner only delivers to URLs that meet all of these rules. If the URL breaks one, Tuner rejects it when you save, or skips delivery.

Rule	Detail
HTTPS only	The URL must start with `https://`.
Publicly reachable	The hostname must resolve to public IP addresses. Hosts that resolve to private, loopback, link-local, multicast or reserved addresses (for example `localhost` or `10.x.x.x`) are rejected.
Not a Tuner API host	The URL can’t point to the Tuner API, such as `api.usetuner.ai`.
No redirects	Tuner doesn’t follow redirects. A `3xx` response counts as a failed delivery.

Delivery

Tuner sends each event as an HTTP POST with a JSON body. Your endpoint should return a 2xx status.

A 2xx response marks the delivery as done.
A 404 response is treated as done and is not retried.
Any other response, a timeout or a connection error counts as a failure, and the delivery is retried.

Setting	Value
Method	`POST`
Request timeout	15 seconds

Headers

Every delivery includes these headers, so you can route an event before you parse the body:

Header	Value
`X-Tuner-Event`	The event type: `call.analyzed`, `alert.fired` or `call.received`.
`X-Tuner-Event-Id`	The event’s `event_id`, same as in the body.
`X-Tuner-Webhook-Version`	The version of the envelope format: `2026-07-02`.

Event envelope

All events share the same envelope, so a single handler can process everything:

event: the event type (call.analyzed, alert.fired or call.received).
event_id: the event type and the subject it’s about, joined by :. See the table below.
created_at: ISO 8601 timestamp of when the event was created.
payload: the event-specific data.
call_id: the provider’s call ID. Only on call.analyzed.

The event_id is built from the event and its subject, so a retried delivery carries the same event_id. Store the IDs you’ve processed and skip repeats.

Event	`event_id` format
`call.analyzed`	`call.analyzed:<provider call ID>`
`alert.fired`	`alert.fired:<alert ID>:<alert trigger ID>`
`call.received`	`call.received:<provider call ID>`

Event types

`call.analyzed`: call analysis complete

Sent for all providers once Tuner finishes analyzing a call. It’s sent once per call; re-running the analysis doesn’t send it again. The payload links to the call in Tuner, so you can route it into ticketing systems, QA queues or internal dashboards.

Field	Description
`payload.tuner_call_url`	Link to the call in Tuner Call Logs.
`payload.provider_agent_id`	The agent’s Agent Remote ID.

{
  "event": "call.analyzed",
  "event_id": "call.analyzed:call_d6e56839d80a34474f2f57f06a7",
  "created_at": "2026-07-03T14:39:33.677818+00:00",
  "payload": {
    "tuner_call_url": "https://app.usetuner.ai/call-logs/8379",
    "provider_agent_id": "agent_5410a3ec3f429c24c36e79e356"
  },
  "call_id": "call_d6e56839d80a34474f2f57f06a7"
}

`alert.fired`: a real-time alert triggered

Sent for all providers when a real-time alert with the Webhook notification channel enabled fires. The payload includes the alert definition, the threshold and time window that were breached, and the call that triggered it.

{
  "event": "alert.fired",
  "event_id": "alert.fired:155:66",
  "created_at": "2026-07-06T03:10:35.868197+00:00",
  "payload": {
    "alert_id": 155,
    "alert_name": "hallucination-happened",
    "severity": "critical",
    "alert_trigger_id": 66,
    "call_id": 8383,
    "agent_id": 466,
    "qualifying_count": 1,
    "threshold_n": 1,
    "window_ms": 3600000,
    "window_start": "2026-06-25T09:18:22+00:00",
    "window_end": "2026-06-25T10:18:22+00:00",
    "triggered_at": "2026-07-06T03:10:35.513644+00:00"
  }
}

`call.received`: provider event forwarding (Vapi and Retell only)

Vapi and Retell support a single webhook URL per agent. When you connect one of these agents to Tuner, Tuner takes that webhook slot, so an automation wired to it (an n8n workflow, a Zapier trigger, a custom server) stops receiving events from the provider. To keep those automations running, Tuner forwards one provider event per call to your webhook URL as a call.received event:

Provider	Forwarded event	Not forwarded
Retell	`call_analyzed`	All other Retell webhook events
Vapi	`end-of-call-report`	All other Vapi server messages

The payload field holds the provider’s original request body, unchanged. Update your handler to read payload instead of the request body root. If an automation relies on an event that isn’t forwarded, it won’t receive it through Tuner.

{
  "event": "call.received",
  "event_id": "call.received:call_d6e56839d80a34474f2f57f06a7",
  "created_at": "2026-07-03T14:37:57.231241+00:00",
  "payload": {
    // The body Retell or Vapi sent, unchanged
  }
}

For other providers (LiveKit, Pipecat, Dograh, custom integrations), calls reach Tuner through the SDK or API, so there is no provider event to forward. Those agents receive call.analyzed and alert.fired only.

Getting Started

Integrations

Evaluation

Observability

Simulation

Datasets

MCP

Guides

Resources

Overview

Setup

URL requirements

Delivery

Headers

Event envelope

Event types

`call.analyzed`: call analysis complete

`alert.fired`: a real-time alert triggered

`call.received`: provider event forwarding (Vapi and Retell only)

Next steps

Configure real-time alerts

Connecting to Retell

​Overview

​Setup

​URL requirements

​Delivery

​Headers

​Event envelope

​Event types

​call.analyzed: call analysis complete

​alert.fired: a real-time alert triggered

​call.received: provider event forwarding (Vapi and Retell only)

​Next steps

Configure real-time alerts

Connecting to Retell

Overview

Setup

URL requirements

Delivery

Headers

Event envelope

Event types

`call.analyzed`: call analysis complete

`alert.fired`: a real-time alert triggered

`call.received`: provider event forwarding (Vapi and Retell only)

Next steps