Webhooks

When a call ends, TopCalls sends a JSON POST to your server with the call details, transcript, recording and analysis. That happens whether the call completed, failed or was cancelled, so you don’t need to poll.

Setting Up Webhooks

You can set a webhook in three places.

Per-Call Webhooks

Set webhook_url when you create a call:

{
  "phone_number": "+14155551234",
  "task": "Confirm appointment...",
  "webhook_url": "https://your-app.com/webhooks/call-complete",
  "webhook_call_status_filter": ["completed", "failed"]
}

With webhook_call_status_filter, the webhook fires only when the call’s call_status (the telephony outcome, such as completed, no-answer or busy) is in the list. Leave it out or empty to get every outcome. Subscriptions ignore it.

Campaign Webhooks

Set config.webhook_url on a campaign, or the webhook field in the campaign editor, and every call it places or answers sends there. config.webhook_call_status_filter works as above.

Account-Level Subscriptions

A subscription gets every matching call on your account, however the call was created:

curl -X POST https://api.topcalls.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "call.completed",
    "url": "https://hooks.your-app.com/topcalls"
  }'

call.completed fires for every call that ends, failed and cancelled ones included, so check status in the payload. To get a single disposition, add its slug: the label lowercased, with each run of other characters replaced by _. A call labelled Booked Callback fires call.completed.booked_callback:

{
  "event": "call.completed.booked_callback",
  "url": "https://hooks.your-app.com/callbacks"
}

filters narrow it further, and every key has to match. A plain value matches by equality, an array matches any of its strings, and a string with % is a SQL LIKE pattern (% is any run of characters, _ is one). The key is_conversion matches calls whose disposition is in the campaign’s conversion outcomes, ignoring case:

{
  "event": "call.completed",
  "url": "https://hooks.your-app.com/conversions",
  "filters": {
    "is_conversion": true,
    "phone_number": "+1555%"
  }
}

Any payload field works as a key. "direction": "inbound", for example, keeps only calls that came in on your numbers. GET /v1/webhooks lists your subscriptions. GET, PATCH and DELETE /v1/webhooks/{webhook_id} read, change or remove one. Full schemas are in the API reference. Test calls from the dashboard’s browser tester never send webhooks.

Webhook Payload

A complete call.completed payload:

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "+14155551234",
  "from_phone_number": "+18005551234",
  "direction": "outbound",
  "status": "completed",
  "call_status": "completed",
  "duration": 2.5,
  "transcript": [
    {
      "id": 1,
      "role": "assistant",
      "text": "Hi, this is Rachel from Bright Dental...",
      "created_at": "2025-12-22T10:30:05.120Z"
    },
    {
      "id": 2,
      "role": "user",
      "text": "Yes, hi...",
      "created_at": "2025-12-22T10:30:08.450Z"
    },
    {
      "id": 3,
      "role": "assistant",
      "text": "",
      "created_at": "2025-12-22T10:32:35.010Z",
      "kind": "end",
      "end_via": "caller"
    }
  ],
  "recording_url": "https://s3.topcalls.ai/2025/12/22/7f3e9a52-1c4b-4d8e-9a6f-2b5c8d1e0f34.mp3",
  "call_summary": "Successfully confirmed appointment...",
  "error_message": null,
  "answered_by": "human",
  "campaign_id": "camp_abc123",
  "lead_id": "lead_xyz789",
  "created_at": "2025-12-22T10:30:00Z",
  "started_at": "2025-12-22T10:30:05Z",
  "end_at": "2025-12-22T10:32:35Z",
  "disposition": "Appointment Booked",
  "is_conversion": true,
  "analysis": {
    "call_outcome": "Appointment Booked",
    "main_objection": null
  },
  "metadata": {
    "patient_id": "pat_123",
    "source": "reminder_system"
  }
}

status is completed, failed or cancelled. duration is in minutes. Each transcript item has an id, a speaker, text and a created_at timestamp with milliseconds. Here the speaker field is role (assistant or user); GET /v1/calls/{call_id} calls the same field user. Spoken turns have no kind. Other items set it:

tool_call: the agent used a tool (tool_name, tool_status of success, failure or unknown, and tool_ok, which is false only on a reported failure and doesn’t prove the action worked)
handoff: one crew member passed the call to another (handoff_from, handoff_to)
signal: the caller went quiet (caller_silent) or the call is near its time limit (caller_time_limit), named in signal, with signal_seconds when known
barge_in: the caller spoke over the agent
end: how the call finished, in end_via: agent, caller, time_limit, voicemail or connection

signal and barge_in items appear only on legacy-mode calls; a Live call never sends them. To keep only speech, skip items that have kind. disposition is the label post-call analysis gave the call, or a platform label: Voicemail, Transferred or No Response. is_conversion is true when that label is in the campaign’s conversion outcomes (case doesn’t matter) and always false on failed calls. direction is outbound when TopCalls placed the call and inbound when it came in on one of your numbers. Either way, phone_number is the other party. caller_name shows up only on inbound payloads: the name the caller’s network sent, or null. If the agent tried a transfer to a person, the payload also carries transferred_to and transfer_status.

Webhook Timing

A completed call’s webhook goes out once the transcript, summary and recording are ready, at least 15 seconds after hang-up. It waits up to about 2.5 minutes for the recording. If the recording still isn’t ready, the webhook goes without recording_url, and nothing adds it later, so GET /v1/calls/{call_id} won’t have it either. Failed and cancelled calls have no recording to wait for, so their webhook goes out right away.

Handling Webhooks

Express.js Example

app.post('/webhooks/call-complete', async (req, res) => {
  // Acknowledge first, then do the slow work
  res.status(200).json({ received: true });

  const call = req.body;
  await updateCRM(call);
  await sendNotification(call);
  await updateAnalytics(call);
});

Securing Your Endpoint

Payloads aren’t signed, so the URL itself is the credential:

Serve the endpoint over HTTPS only.
Put an unguessable token in the path or query string (for example https://your-app.com/webhooks/tc_8f3k2m9x) and reject requests without it.
To double-check a payload before acting on it, fetch GET /v1/calls/{call_id} and compare.

Webhook Retries

Your endpoint has 10 seconds to answer with a 2xx. A 4xx on any attempt is final and never retried. A timeout, network error or 5xx is retried up to 5 times, 1, 5, 15, 30 and then 60 minutes after the previous failure, for 6 attempts in all. If the last one fails, the delivery is dropped. The call itself is still there in GET /v1/calls/{call_id}.

Best Practices

Answer with a 2xx right away and process in the background. Slow work inside the handler runs into the 10-second timeout.
Expect the same call more than once and deduplicate on call_id.
Catch errors in your handler so one bad payload can’t crash the server.
Log what you receive. It makes debugging much easier.
Keep the URL secret: HTTPS, an unguessable token, and never in public logs or repositories.

Testing Webhooks

To test locally, expose your server with ngrok or point the webhook at webhook.site:

ngrok http 3000

Then use the tunnel URL as the webhook:

{
  "webhook_url": "https://abc123.ngrok.io/webhooks/call-complete"
}

Getting Started

Core Concepts

Guides

Use Cases

Integrations

Setting Up Webhooks

Per-Call Webhooks

Campaign Webhooks

Account-Level Subscriptions

Webhook Payload

Webhook Timing

Handling Webhooks

Express.js Example

Securing Your Endpoint

Webhook Retries

Best Practices

Testing Webhooks

Next Steps

Webhooks & Events

API Reference

​Setting Up Webhooks

​Per-Call Webhooks

​Campaign Webhooks

​Account-Level Subscriptions

​Webhook Payload

​Webhook Timing

​Handling Webhooks

​Express.js Example

​Securing Your Endpoint

​Webhook Retries

​Best Practices

​Testing Webhooks

​Next Steps

Webhooks & Events

API Reference

Setting Up Webhooks

Per-Call Webhooks

Campaign Webhooks

Account-Level Subscriptions

Webhook Payload

Webhook Timing

Handling Webhooks

Express.js Example

Securing Your Endpoint

Webhook Retries

Best Practices

Testing Webhooks

Next Steps