Receive Real-Time AI Call Events with Webhooks

Webhooks let you receive real-time notifications when events happen during calls. Simple AI sends HTTP POST requests to your server so your application can react to call events as they occur — and trigger full workflows in response.

Available Events

Event	Sent when
`call.started`	A call is created and the agent is connecting
`call.transcript_update`	A new entry is added to the call transcript
`call.transferred`	The agent transfers the call
`call.completed`	The call has finished

Webhooks are not sent for test calls.

Setting Up Webhooks

You can create webhooks in the dashboard under Configuration > Webhooks (/organization/settings/webhooks), which opens the webhook portal, or through the API. When you create a webhook, you provide:

URL — the endpoint on your server that will receive the events
Events — which event types you want to subscribe to. If you do not choose any, the endpoint receives all of them.

Simple AI will send a POST request to your URL whenever a subscribed event occurs.

Webhook Format

Every event is a JSON object that names the event and the call it belongs to:

{
  "call_id": "123e4567-e89b-12d3-a456-426614174000",
  "event_type": "call.completed"
}

Field	Description
`call_id`	The UUID of the call this event relates to
`event_type`	The event that occurred

call.started also includes direction, from_number, and to_number. See each event’s reference page for its full payload. Events are notifications, not snapshots. To read the call’s status, transcript, recording, or analysis, get the call using the call_id from the event. Each request also carries three headers:

Header	Description
`svix-id`	A unique identifier for the message. It stays the same when a delivery is retried.
`svix-timestamp`	When the delivery attempt was made, as a Unix timestamp in seconds
`svix-signature`	The signature to verify, described below

Verifying Signatures

Every webhook is signed with a secret that is unique to your endpoint. Verify the signature before you process an event so that you only act on requests sent by Simple AI. Find the signing secret for an endpoint in the webhook portal, under Configuration > Webhooks in the dashboard. It starts with whsec_. Verify against the raw request body, before any JSON parsing. Parsing and re-serializing the body changes it and causes verification to fail.

import { Webhook } from 'svix';

const webhook = new Webhook(process.env.SIMPLE_WEBHOOK_SECRET);

// rawBody is the request body as a string, exactly as received
const event = webhook.verify(rawBody, {
  'svix-id': request.headers['svix-id'],
  'svix-timestamp': request.headers['svix-timestamp'],
  'svix-signature': request.headers['svix-signature'],
});

import os
from svix.webhooks import Webhook

webhook = Webhook(os.environ["SIMPLE_WEBHOOK_SECRET"])

# raw_body is the request body as bytes or a string, exactly as received
event = webhook.verify(raw_body, {
    "svix-id": request.headers["svix-id"],
    "svix-timestamp": request.headers["svix-timestamp"],
    "svix-signature": request.headers["svix-signature"],
})

verify returns the parsed event and throws if the signature does not match or the timestamp is too old. To verify without a library, compute an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw body} using the base64-decoded part of the secret after whsec_, base64-encode the result, and compare it to the signatures in svix-signature. That header holds one or more space-separated entries in the form v1,<signature>; accept the request if any of them matches.

Pre-Call and Post-Call Workflows

Webhooks are the building blocks for full pre-call and post-call workflows. Rather than just reacting to a single event, you can use them to trigger entire journeys — looking up caller data before a call, or orchestrating a multi-step follow-up process after a call ends. See Workflows for detailed guidance on building pre-call and post-call workflows, including examples of multi-step orchestration.

Retry Policy

If your endpoint is unavailable or returns a non-2xx status code, Simple AI retries the delivery with exponential backoff. A retried delivery has the same svix-id as the original.

Best Practices

Respond quickly — return a 2xx status code as soon as you receive the webhook. If you need to do heavy processing, queue the work and respond immediately.
Handle duplicates — due to retries, you may receive the same event more than once. Record the svix-id of each message you process and skip any you have already seen.
Verify signatures — always check the webhook signature to confirm the request is authentic.
Do not rely on order — events for a call can arrive out of order. Get the call to read its current state.
Think in workflows — a call.completed event does not have to map to a single action. Use it as the trigger for a full post-call journey that branches based on tags, analyzer results, or call outcome.
Monitor failures — if your endpoint starts returning errors, webhooks will be retried but eventually dropped. The webhook portal lists each delivery attempt with the response your endpoint returned, and lets you resend a message.

Get Started

Core Concepts

Calls

Channels

Inbox

Campaigns

Journeys

Post-Call Intelligence

Agent Capabilities

Action Authentication

Integrations

CCaaS Integrations

SDK

Help Center

Receive Real-Time AI Call Events with Webhooks

Available Events

Setting Up Webhooks

Webhook Format

Verifying Signatures

Pre-Call and Post-Call Workflows

Retry Policy

Best Practices

API Reference

​Available Events

​Setting Up Webhooks

​Webhook Format

​Verifying Signatures

​Pre-Call and Post-Call Workflows

​Retry Policy

​Best Practices

​API Reference

Available Events

Setting Up Webhooks

Webhook Format

Verifying Signatures

Pre-Call and Post-Call Workflows

Retry Policy

Best Practices

API Reference