Webhooks

Webhooks let your backend react to what your agents do without polling. Register a URL and the events you care about, and AssemblyAI sends a signed POST to that URL whenever one fires. For phone calls, the payload includes ready-to-download recording and transcript URLs.

Session or call ends ──► AssemblyAI ──POST──► https://your-app.com/webhooks/assemblyai
                                                  │
                                          verify X-AAI-Signature,
                                          then act on the event

Base URL: https://agents.assemblyai.com. Send your API key in the Authorization header (a Bearer prefix is accepted), same as the rest of the API.

Set up a webhook handler

The reference section below covers every field and rule.

Generate a signing secret

Every delivery is signed with a secret you choose. Generate one, store it somewhere your handler can read it, and keep it. The API never returns it.

export AAI_WEBHOOK_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
echo $AAI_WEBHOOK_SECRET

It must be 32 to 256 printable ASCII characters with no whitespace.

Write the handler

Your handler does two things: verify the signature, then acknowledge with a 2xx as fast as possible. Do any slow work after responding.

import hashlib
import hmac
import os
import time

from fastapi import FastAPI, Header, HTTPException, Request

SECRET = os.environ["AAI_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 300

app = FastAPI()


def verify(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    if not signature_header:
        return False
    fields = {}
    for pair in signature_header.split(","):
        key, sep, value = pair.partition("=")
        if sep:
            fields[key.strip()] = value.strip()
    raw_t, v1 = fields.get("t"), fields.get("v1")
    if not raw_t or not v1:
        return False
    try:
        timestamp = int(raw_t)
    except ValueError:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.".encode("utf-8") + raw_body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, v1):
        return False
    return abs(int(time.time()) - timestamp) <= TOLERANCE_SECONDS


@app.post("/webhooks/assemblyai")
async def handle(request: Request, x_aai_signature: str | None = Header(default=None)):
    raw_body = await request.body()
    if not verify(raw_body, x_aai_signature, SECRET):
        raise HTTPException(status_code=401, detail="invalid signature")

    event = await request.json()
    process(event)
    return {"ok": True}


def process(event: dict) -> None:
    if event["event"].startswith("call."):
        call = event["call"]
        print(event["event"], call["call_id"], call.get("recording_url"))
    else:
        print(event["event"], event["session"]["session_id"])

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.AAI_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const fields = Object.fromEntries(
    signatureHeader.split(",").map((pair) => {
      const i = pair.indexOf("=");
      return [pair.slice(0, i).trim(), pair.slice(i + 1).trim()];
    })
  );
  const t = Number.parseInt(fields.t, 10);
  if (!Number.isFinite(t) || !fields.v1) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(fields.v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return Math.abs(Math.floor(Date.now() / 1000) - t) <= TOLERANCE_SECONDS;
}

const app = express();

// express.raw keeps the body as the exact bytes that were signed.
app.post("/webhooks/assemblyai", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.get("X-AAI-Signature"), SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  console.log(event.event, event.call?.call_id ?? event.session?.session_id);
  res.sendStatus(200);
});

app.listen(8000);

Run it: uvicorn receiver:app --port 8000 or node receiver.mjs.

Verify the raw request body bytes, exactly as shown above. If you parse the JSON and re-serialise it before hashing, the bytes differ and every signature fails with 401. A 401 is not retried, so those events are lost.

Expose it over HTTPS

The subscription URL must be https:// and publicly reachable; it’s checked when you create the subscription. For local development, put ngrok in front of your handler:

ngrok http 8000

Copy the https://….ngrok-free.app URL it prints. In production, use your own HTTPS host.

Create the subscription

Register your URL, the events you want, and the secret from step 1. Pass agent_id to receive events for one agent, or leave it out for every agent on your account.

curl -X POST https://agents.assemblyai.com/v1/webhook-subscriptions \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/assemblyai",
    "events": ["call.connected", "call.ended", "call.failed"],
    "secret": "'"$AAI_WEBHOOK_SECRET"'",
    "agent_id": "7ad24396-b822-4dca-871a-be9cc4781cf9"
  }'

# pip install requests
import os
import requests

resp = requests.post(
    "https://agents.assemblyai.com/v1/webhook-subscriptions",
    headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
    json={
        "url": "https://your-app.com/webhooks/assemblyai",
        "events": ["call.connected", "call.ended", "call.failed"],
        "secret": os.environ["AAI_WEBHOOK_SECRET"],
        "agent_id": "7ad24396-b822-4dca-871a-be9cc4781cf9",
    },
)
resp.raise_for_status()
print(resp.json()["id"])

// Node 18+ has fetch built in
const res = await fetch("https://agents.assemblyai.com/v1/webhook-subscriptions", {
  method: "POST",
  headers: {
    Authorization: process.env.ASSEMBLYAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/assemblyai",
    events: ["call.connected", "call.ended", "call.failed"],
    secret: process.env.AAI_WEBHOOK_SECRET,
    agent_id: "7ad24396-b822-4dca-871a-be9cc4781cf9",
  }),
});
const data = await res.json();
console.log(data.id);

Save the id from the response. You need it to update or delete the subscription later.

Phone calls emit call.* events only, never session.*. If your agent answers phone calls, subscribe to call.connected, call.ended, and call.failed. A subscription to session events alone receives nothing for telephony. Use session.started and session.completed for WebSocket sessions.

Trigger an event and watch it arrive

Call your agent’s phone number, or start a WebSocket session against it, then end it. Within a few seconds your handler logs the delivery.If nothing arrives, check the delivery history. Every attempt is recorded against the session (for a call, the session id is the call_id):

curl https://agents.assemblyai.com/v1/sessions/$SESSION_ID/webhook-deliveries \
  -H "Authorization: $ASSEMBLYAI_API_KEY"

{
  "deliveries": [
    {
      "id": "9a641d63-3ecf-497d-8ffa-07bf10c5f009",
      "subscription_id": "cb1f65e4-056e-4075-b3db-311677ce04d8",
      "session_id": "sess_2139906f39a34c598627e8fbb6fb5fe5",
      "status": "delivered",
      "attempt_count": 1,
      "http_status_code": 200,
      "error": null,
      "delivered_at": "2026-09-16T10:27:28.104000Z",
      "next_retry_at": null,
      "created_at": "2026-09-16T10:27:27.887017Z"
    }
  ],
  "has_more": false
}

A status of failed with "error": "HTTP 401: invalid signature" means your handler rejected it, usually because of the raw-bytes problem from step 2 or a secret mismatch. See Troubleshooting for the rest.

Use the event

What you do next depends on the channel:

Phone calls: call.ended includes recording_url and transcript_url. They’re presigned, work immediately, and expire one hour after the event, so download the files rather than storing the URLs. call.connected has both set to null.
WebSocket sessions: session.completed fires when the session ends, before the recording and transcript are written (s3_prefix is null in the payload). They typically appear within about 90 seconds. Fetch them with GET /v1/sessions/{session_id} from the Sessions API, polling every few seconds until artifacts is non-empty.

If you only need metadata (duration, close reason, agent, phone numbers), it is already in the webhook body. No follow-up request is needed.

Before you go to production

Deduplicate on event_id. Delivery is at-least-once, and the same event can arrive more than once. event_id is stable across retries; X-AAI-Delivery-Id changes per attempt, so don’t dedupe on it.
Respond within 15 seconds. Return 2xx first, do slow work after. A slow handler gets retried, which means duplicates.
Know what isn’t retried. Any 4xx other than 408, 425, and 429 is treated as your endpoint rejecting the event and is not retried. 5xx, timeouts, and connection errors are.
Don’t rely on ordering. call.connected is not guaranteed to arrive before call.ended.
Register the final URL. Redirects are not followed; a 301 counts as a failure.
Rotate secrets with PATCH. Sending a new secret bumps secret_version. Deliveries already in flight were signed with the old one, so accept both during the changeover.

Reference

Events

Event	Fires when	Payload object	Channel
`session.started`	A WebSocket session begins.	`session`	WebSocket
`session.completed`	A WebSocket session ends.	`session`	WebSocket
`call.connected`	A phone call is answered by an agent.	`call`	Telephony
`call.ended`	A phone call finishes.	`call`	Telephony
`call.failed`	A phone call could not be placed or answered.	`call`	Telephony

Delivery headers

Header	Example	Purpose
`X-AAI-Signature`	`t=1789554447,v1=b209cd2c…`	Timestamped HMAC. See Signature.
`X-AAI-Event`	`call.ended`	The event type, for routing without parsing the body.
`X-AAI-Delivery-Id`	`2f45e3eb-c70e-4dff-8ae1-a6e7560acdf9`	Identifies this delivery attempt. Changes on every retry.
`User-Agent`	`AssemblyAI-Webhook-Delivery/1.0`

Signature

X-AAI-Signature: t=1789554447,v1=b209cd2cb55dc9afa6bb182fa165cfc299c71669b867fe2f1507f3ff11082a16

t: Unix timestamp in seconds when the delivery was signed.
v1: hex HMAC-SHA256, keyed with your subscription secret, over the string "{t}." followed by the raw request body bytes.

Recompute v1, compare in constant time, and reject any delivery whose t is more than 300 seconds from your clock. The timestamp is what stops a captured request being replayed.

Payloads

Session events carry a session object:

{
  "event_id": "bf36882c-71ac-41b8-839d-48a24bd3169e",
  "event": "session.completed",
  "timestamp": "2026-09-16T10:27:27.887017+00:00",
  "session": {
    "session_id": "sess_2139906f39a34c598627e8fbb6fb5fe5",
    "account_id": 123456,
    "agent_id": "3ee4f5fa-0a5a-41f8-abb1-3fa50fe253fd",
    "status": "completed",
    "duration_seconds": 10.150365,
    "public_close_reason": "client_end",
    "s3_prefix": null,
    "created_at": "2026-09-16T10:27:17.391140Z",
    "ended_at": "2026-09-16T10:27:27.541000Z"
  }
}

session.started has the same shape with "status": "created" and duration_seconds, ended_at, and public_close_reason set to null. Call events carry a call object:

{
  "event_id": "df5cb35c-b02d-49f2-8420-f77fee999c8f",
  "event": "call.ended",
  "timestamp": "2026-09-16T10:46:41.770690+00:00",
  "call": {
    "call_id": "call_c03900346e334c7c8420fd7aac3ce29c",
    "session_id": "call_c03900346e334c7c8420fd7aac3ce29c",
    "account_id": 123456,
    "agent_id": "7ad24396-b822-4dca-871a-be9cc4781cf9",
    "status": "ended",
    "direction": "inbound",
    "from_number": "+15555550123",
    "to_number": "+15555550199",
    "created_at": "2026-09-16T10:45:45.169858",
    "ended_at": "2026-09-16T10:46:41.397419",
    "recording_url": "https://…/recording/audio.ogg?…&Expires=1789559201",
    "transcript_url": "https://…/timeline/timeline.json?…&Expires=1789559201"
  }
}

For a phone call, call_id and session_id are the same value. from_number is the caller’s real number, so treat the payload as personal data.

Subscription fields

Field	Required	Notes
`url`	Yes	Where deliveries are POSTed. Must be `https://` and resolve in public DNS. Private and loopback addresses are rejected.
`events`	Yes	One or more of the events above. No duplicates.
`secret`	Yes	32 to 256 printable ASCII characters, no whitespace. Never returned; the response carries a `secret_version` integer that increments on rotation.
`agent_id`	No	Scope to one agent. Omit for account-wide events.
`enabled`	No	Defaults to `true`. Set `false` to pause deliveries without deleting the subscription.

Manage subscriptions

# List (paginated, newest first). Paused subscriptions are hidden unless you add ?include_disabled=true.
curl "https://agents.assemblyai.com/v1/webhook-subscriptions?include_disabled=true" -H "Authorization: $ASSEMBLYAI_API_KEY"

# Retrieve one
curl https://agents.assemblyai.com/v1/webhook-subscriptions/$SUBSCRIPTION_ID -H "Authorization: $ASSEMBLYAI_API_KEY"

# Update: change the URL or events, pause, or rotate the secret (bumps secret_version)
curl -X PATCH https://agents.assemblyai.com/v1/webhook-subscriptions/$SUBSCRIPTION_ID \
  -H "Authorization: $ASSEMBLYAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# Delete (also removes its delivery history)
curl -X DELETE https://agents.assemblyai.com/v1/webhook-subscriptions/$SUBSCRIPTION_ID -H "Authorization: $ASSEMBLYAI_API_KEY"

# pip install requests
import os
import requests

base = "https://agents.assemblyai.com/v1/webhook-subscriptions"
headers = {"Authorization": os.environ["ASSEMBLYAI_API_KEY"]}
subscription_id = os.environ["SUBSCRIPTION_ID"]

# List (paginated, newest first). Paused subscriptions are hidden unless include_disabled=true.
resp = requests.get(base, headers=headers, params={"include_disabled": "true"})
resp.raise_for_status()
print(resp.json()["subscriptions"])

# Retrieve one
resp = requests.get(f"{base}/{subscription_id}", headers=headers)
resp.raise_for_status()
print(resp.json())

# Update: change the URL or events, pause, or rotate the secret (bumps secret_version)
resp = requests.patch(f"{base}/{subscription_id}", headers=headers, json={"enabled": False})
resp.raise_for_status()
print(resp.json())

# Delete (also removes its delivery history)
resp = requests.delete(f"{base}/{subscription_id}", headers=headers)
resp.raise_for_status()

// Node 18+ has fetch built in
const base = "https://agents.assemblyai.com/v1/webhook-subscriptions";
const auth = { Authorization: process.env.ASSEMBLYAI_API_KEY };
const subscriptionId = process.env.SUBSCRIPTION_ID;

// List (paginated, newest first). Paused subscriptions are hidden unless include_disabled=true.
let res = await fetch(`${base}?include_disabled=true`, { headers: auth });
console.log((await res.json()).subscriptions);

// Retrieve one
res = await fetch(`${base}/${subscriptionId}`, { headers: auth });
console.log(await res.json());

// Update: change the URL or events, pause, or rotate the secret (bumps secret_version)
res = await fetch(`${base}/${subscriptionId}`, {
  method: "PATCH",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ enabled: false }),
});
console.log(await res.json());

// Delete (also removes its delivery history)
res = await fetch(`${base}/${subscriptionId}`, { method: "DELETE", headers: auth });

PATCH accepts any of url, events, secret, and enabled.

Delivery history

# Every attempt for a session (for a call, use the call_id)
curl https://agents.assemblyai.com/v1/sessions/$SESSION_ID/webhook-deliveries \
  -H "Authorization: $ASSEMBLYAI_API_KEY"

# Only the most recent attempt per subscription
curl https://agents.assemblyai.com/v1/sessions/$SESSION_ID/webhook-deliveries/latest \
  -H "Authorization: $ASSEMBLYAI_API_KEY"

Each entry has status (pending, delivered, or failed), attempt_count, http_status_code, error, delivered_at, and next_retry_at. Deleting a subscription removes its entries.

Troubleshooting

Symptom	Likely cause
Every delivery `failed` with `HTTP 401: invalid signature`	Hashing a re-serialised body instead of the raw bytes, verifying without the `t.` prefix, or a secret mismatch between the subscription and your handler
Intermittent `401`	Handler clock skew beyond the 300-second tolerance. Check NTP.
Nothing arrives for phone calls	Subscribed to `session.` only. Telephony emits `call.`.
Nothing arrives at all	Subscription paused, scoped to a different `agent_id`, or the URL redirects
Duplicate events in your system	Not deduplicating on `event_id`
Occasional failures under load	Handler exceeding the 15-second read timeout

Endpoints

Method	Path	Description
`POST`	`/v1/webhook-subscriptions`	Create a subscription.
`GET`	`/v1/webhook-subscriptions`	List your subscriptions.
`GET`	`/v1/webhook-subscriptions/{id}`	Retrieve one.
`PATCH`	`/v1/webhook-subscriptions/{id}`	Update `url`, `events`, `secret`, or `enabled`.
`DELETE`	`/v1/webhook-subscriptions/{id}`	Delete.
`GET`	`/v1/sessions/{session_id}/webhook-deliveries`	Every delivery attempt for a session.
`GET`	`/v1/sessions/{session_id}/webhook-deliveries/latest`	The most recent attempt per subscription.

Getting started

Create & manage agents

Agent behavior

Conversational experience

Deploy

Test

After a session

Reference

API reference

Set up a webhook handler

Before you go to production

Reference

Events

Delivery headers

Signature

Payloads

Subscription fields

Manage subscriptions

Delivery history

Troubleshooting

Endpoints

​Set up a webhook handler

​Before you go to production

​Reference

​Events

​Delivery headers

​Signature

​Payloads

​Subscription fields

​Manage subscriptions

​Delivery history

​Troubleshooting

​Endpoints

Set up a webhook handler

Before you go to production

Reference

Events

Delivery headers

Signature

Payloads

Subscription fields

Manage subscriptions

Delivery history

Troubleshooting

Endpoints