> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# Webhooks Overview

> Receive real-time call lifecycle events from FormantAI Voice.

Webhooks let your backend receive call events without polling. Configure webhook targets on an agent, then FormantAI sends an HTTP POST to your endpoint whenever a subscribed terminal event occurs.

## How webhooks work

Add an HTTPS endpoint to the agent's Webhook tab.

Subscribe the target to events such as `call.completed`, `call.no_answer`, and `call.failed`.

The agent places or receives calls and stores the conversation result.

Your endpoint receives a signed JSON payload with call data, results, retry details, and optional transcript/recording URL.

Return a `2xx` response quickly and process heavier work asynchronously.

## Event lifecycle

```text
Call initiated
      |
      v
Call rings / connects / fails
      |
      v
Terminal status is stored
      |
      v
Subscribed webhook targets receive the event
```

## Endpoint requirements

* Use HTTPS in production.
* Accept `POST` requests with `Content-Type: application/json`.
* Return a `2xx` response quickly.
* Verify `X-FormantAI-Signature` before trusting the payload.
* Deduplicate events using `event_id`.
* Queue expensive work instead of blocking the webhook response.

## Recommended starting point

For most production integrations, subscribe to `call.completed`, `call.no_answer`, `call.busy`, `call.failed`, and `call.unreachable`. Add lower-level failure events when your operations team needs more debugging detail.

Add targets from the dashboard.

Validate every incoming request.