> 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.

# Webhook Events

> Event types FormantAI sends to webhook targets.

Webhook targets receive only the events they subscribe to.

| Event                   | Trigger                                                              | Typical use                                                       |
| ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `call.completed`        | Call connected and ended successfully.                               | Save transcript, structured results, duration, and recording URL. |
| `call.failed`           | Call failed during setup or could not connect.                       | Alert, debug, or mark the attempt failed.                         |
| `call.busy`             | Recipient line was busy.                                             | Update CRM status and wait for retry policy.                      |
| `call.no_answer`        | Recipient did not answer.                                            | Schedule follow-up or wait for retry.                             |
| `call.socket_failure`   | Call connected at telephony layer but voice streaming did not start. | Investigate voice streaming or provider issues.                   |
| `call.telephony_failed` | Telephony provider failed after call initiation.                     | Alert operations and reconcile provider status.                   |
| `call.unreachable`      | Destination number could not be reached.                             | Mark number invalid/unreachable or request a new contact.         |

## Event fields

Every event uses the same top-level envelope:

| Field        | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `event_id`   | string | Unique ID for this webhook delivery. Use for dedupe. |
| `event_type` | string | One of the event types above.                        |
| `timestamp`  | string | ISO 8601 timestamp when FormantAI created the event. |
| `data`       | object | Event-specific payload.                              |

## Event handling pattern

```javascript
app.post("/webhooks/formant", async (req, res) => {
  const event = req.body;

  await saveEventOnce(event.event_id, event);

  switch (event.event_type) {
    case "call.completed":
      await handleCompletedCall(event.data);
      break;
    case "call.no_answer":
    case "call.busy":
      await markRetryableAttempt(event.data);
      break;
    default:
      await logCallOutcome(event.data);
  }

  res.status(204).send();
});
```