Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usesimple.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
call.transcript_update

Sent whenever there is a new update to the call transcript during the conversation. Use this to follow conversations in real time, display live transcripts, or trigger actions based on what is being said. View payload details

​
call.completed

Sent when a call has finished. This is the starting point for your post-call workflow — syncing data, sending follow-ups, updating tickets, notifying your team, or any other downstream processing. View payload details

​
Setting Up Webhooks

You can create webhooks through the dashboard or 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
Simple AI will send a POST request to your URL whenever a subscribed event occurs.

​
Webhook Format

All webhook events follow a consistent structure: 
{
  "event_type": "call.completed",
  "event_id": "evt_Wqb1k73rXprtTm7Qdlr38G",
  "payload": {
    "call_id": "123e4567-e89b-12d3-a456-426614174000",
    "attempt": 1
  }
}
FieldDescription
event_typeThe event that occurred (e.g., call.completed, call.transcript_update)
event_idA unique identifier for this webhook delivery
payload.call_idThe UUID of the call this event relates to
payload.attemptWhich delivery attempt this is (starts at 1)

​
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. The attempt field in the payload tells you which attempt this delivery represents.

​
Security

Webhooks include a signature header that lets you verify the request came from Simple AI. Always validate this signature before processing webhook data to prevent spoofed requests.

​
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. Design your handler to be idempotent (processing the same event twice should be safe).
  • Verify signatures — always check the webhook signature to confirm the request is authentic.
  • 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. Make sure your endpoint is reliable.

​
API Reference