Webhooks

Webhooks Overview

View as Markdown

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

1

Configure target

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

2

Select events

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

3

Call runs

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

4

FormantAI POSTs event

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

5

Your server acknowledges

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

Event lifecycle

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.

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.

Configure Webhooks

Add targets from the dashboard.

Verify Signatures

Validate every incoming request.