> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Events

> Receive notifications when calls finish. Understand the event model, delivery timing, and retry behavior.

## What Are Webhooks?

Webhooks are HTTP callbacks that TopCalls sends to your server when events occur. They're the best way to integrate TopCalls with your existing systems.

<CardGroup cols={2}>
  <Card title="Real-Time Updates" icon="bolt">
    Get notified when calls complete or fail. No polling required.
  </Card>

  <Card title="Complete Data" icon="database">
    Receive full call details, transcripts, recordings, and analysis in a single webhook payload.
  </Card>

  <Card title="Reliable Delivery" icon="shield-check">
    Built-in retry logic ensures webhooks are delivered even if your server is temporarily unavailable.
  </Card>

  <Card title="Filterable" icon="filter">
    Subscribe to specific dispositions or conversions instead of receiving every event.
  </Card>
</CardGroup>

## How Events Are Delivered

There are two delivery channels:

| Channel                    | How to set up                                       | What it receives                                                            |
| -------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| Per-call `webhook_url`     | Set on `POST /v1/calls` (or in the campaign editor) | One payload when that call completes, fails, or is cancelled                |
| Account-level subscription | `POST /v1/webhooks`                                 | Every matching event on the account, regardless of how the call was created |

## Available Events

Subscriptions use these event names:

| Event                          | When It Fires                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `call.completed`               | Any call finishes and post-call processing is done                                 |
| `call.completed.<disposition>` | A call finishes with a specific disposition, e.g. `call.completed.booked_callback` |

The disposition suffix is a slug of the label assigned by post-call analysis (`Booked Callback` becomes `booked_callback`). Combine events with `filters` on the subscription, including the `is_conversion` flag, to narrow delivery further.

<Note>
  The event names `lead.status_changed`, `campaign.activated`, and `campaign.paused` are reserved for future use. The API accepts subscriptions for them, but they do not fire yet.
</Note>

Per-call webhooks carry a `status` field (`completed`, `failed`, or `cancelled`), so a single endpoint can handle successful and failed calls.

## Webhook Timing

### Successful Calls

Webhooks are sent **\~15 seconds after call ends** to ensure:

* Recording URL is available
* Transcript is complete
* Call summary is generated (if configured)

### Failed Calls

Webhooks are sent **immediately** when the call fails (no recording to wait for).

## Webhook Retries

TopCalls automatically retries failed webhook deliveries:

* **Initial attempt**: Immediate
* **Retry 1**: After 1 minute
* **Retry 2**: After 5 minutes
* **Retry 3**: After 15 minutes
* **Retry 4**: After 30 minutes
* **Retry 5**: After 1 hour

After 5 retries, the webhook is marked as failed. You can still retrieve call data via the API.

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to set up and handle webhooks in your application.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    See the complete API documentation.
  </Card>
</CardGroup>