Using Webhooks
Webhooks let you receive real-time HTTP callbacks when events happen in Agni — like when a call starts, ends, or when post-call analysis is ready. Instead of polling our API, we push data to your server instantly.How It Works
Configure your endpoint
Set up a publicly accessible HTTPS endpoint on your server that can receive POST requests.
Webhook Events
The primary webhook event iscall.completed, dispatched automatically when a call session ends.
| Event | Trigger | Payload Includes |
|---|---|---|
call.completed | Call session ends | Full call data, transcripts, recording, sentiment, post-call analysis |
Full Payload Reference
See the complete After-Call Webhook API reference for every field in the payload, with types and descriptions.
call.completed Payload
When a call ends, Agni sends the complete call record including metadata, transcripts, AI analysis, and costs:
Key Fields
| Field | Type | Description |
|---|---|---|
status | string | completed, failed, no_answer, busy, voicemail |
channel | string | voice (phone), web (browser), sip |
disconnect_reason | string | customer_hangup, agent_hangup, error |
post_call_analysis.sentiment | string | positive, neutral, negative |
post_call_analysis.disposition | string | e.g. meeting_booked, not_interested, callback_requested |
post_call_analysis.goals_met | boolean | Whether the agent achieved its objective |
transcripts[] | array | Full conversation, ordered by timestamp_ms |
Setting Up Your Webhook
Via Dashboard
- Navigate to Agents → Select your agent
- Open the Webhook Settings tab in the right sidebar
- Enter your endpoint URL (must be HTTPS)
- Select which events to subscribe to
- Click Save
Via API
cURL
Example Webhook Receivers
Node.js (Express)
Node.js (Express)
Python (Flask)
Python (Flask)
Retry Policy
If your endpoint returns a non-2xx response or times out (30 seconds), Agni retries with exponential backoff:| Attempt | Delay |
|---|---|
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |
| 4th retry | 1 hour |
| Final retry | 6 hours |
Best Practices
Always return 200 quickly
Process the webhook asynchronously. Return 200 immediately and handle the data in a background job.
Handle duplicates
Use the
call_id as an idempotency key. The same event may be delivered more than once during retries.Validate payloads
Check that the event type and required fields are present before processing. Ignore unknown event types gracefully.
Use HTTPS
Webhook URLs must use HTTPS. We do not send payloads over unencrypted connections.
Troubleshooting
Not receiving webhooks
Not receiving webhooks
- Verify your endpoint URL is correct and publicly accessible
- Check that your server returns 200 status within 30 seconds
- Ensure your firewall allows incoming POST requests from Agni’s IP ranges
- Check the webhook logs in your agent’s settings
Receiving duplicate events
Receiving duplicate events
This is normal during retries. Implement idempotency using the
call_id field — check if you’ve already processed that event before acting on it.Webhook URL keeps failing
Webhook URL keeps failing
After 5 consecutive failures, webhooks pause. Fix your endpoint, then re-save the webhook URL in agent settings to resume delivery.

