Skip to main content

​
How webhooks work

When a call event occurs, OneInbox sends an HTTP POST to your server with the event payload. Your server must respond with 2xx within a few seconds — if it doesn’t, OneInbox retries delivery. Setting up a webhook means you don’t need to poll GET /v1/calls/<id> repeatedly. OneInbox pushes the data to you the moment the event fires.

​
Create a webhook

Set up a webhook by providing a URL on your server and the events you want to receive. OneInbox will send a POST request to that URL every time one of those events fires. 
curl -X POST https://api.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Call events",
    "url": "https://your-server.com/webhooks/oneinbox",
    "events": ["call.started", "call.ended", "call.analyzed", "call.failed", "call.recording.available", "transcript.partial", "transcript.final"]
  }'

{
  "id": "wh_abc123",
  "name": "Call events",
  "url": "https://your-server.com/webhooks/oneinbox",
  "events": ["call.started", "call.ended", "transcript.final"]
}
Save the id — you’ll need it to update or delete the webhook.

​
Supported events

EventWhen it fires
call.startedCall connects and the agent begins the session
call.endedCall ends — agent or caller hung up
call.analyzedAI analysis (summary, outcome) is ready after the call
call.failedCall failed to connect
call.recording.availableCall recording is ready and accessible
transcript.partialPartial transcript update during an active call
transcript.finalFull transcript is ready (fires after call.ended)

​
Event payloads

​
call.started

Fires when a call connects and the agent starts the session. Use this to log call start times or trigger “call in progress” updates in your CRM. 
{
  "event": "call.started",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "created_at": "2026-06-01T10:00:00Z"
}

​
call.ended

Fires when a call ends. This payload includes the AI-generated outcome and summary — the most commonly used event for CRM updates, lead routing, and reporting. 
{
  "event": "call.ended",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm.",
  "analysis": {
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  }
}

​
call.analyzed

Fires after the call ends once the AI has finished generating the summary and outcome. Use this to trigger CRM updates or lead routing based on the call result. 
{
  "event": "call.analyzed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm."
}

​
call.failed

Fires when a call fails to connect. Use this to log failures, trigger retries, or alert your team. 
{
  "event": "call.failed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "reason": "no-answer"
}

​
call.recording.available

Fires when the call recording has been processed and is ready to access. Use this to store or share recordings after a call. 
{
  "event": "call.recording.available",
  "call_id": "call_abc123",
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3"
}

​
transcript.partial

Fires during an active call with a partial transcript update. Use this for real-time monitoring or live agent assist — note that partial transcripts may change as the call continues. 
{
  "event": "transcript.partial",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." }
  ]
}

​
transcript.final

Fires after call.ended once the full transcript is ready. Use this when you need the complete message-by-message conversation log — for example, to log it in your database or send it to a CRM. 
{
  "event": "transcript.final",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." },
    { "role": "agent", "content": "Of course! Let me get that booked for you." }
  ]
}

​
Test a webhook

Send a test delivery to confirm your server is receiving events correctly before going live: 
curl -X POST https://api.oneinbox.ai/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer <api_key>"
Your server should receive a test POST with a sample payload. Check your server logs to confirm it arrives and that your endpoint returns 2xx.

​
Per-call webhook override

You can send events for a specific call to a different URL without changing your global webhook config. This is useful when you’re routing different campaigns or batches to separate downstream systems — for example, one URL for inbound calls and another for outbound. Pass webhook_url when creating the call: 
curl -X POST https://api.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "webhook_url": "https://your-server.com/this-campaign-only"
  }'
The events for this call go to webhook_url instead of (or in addition to) any global webhooks you have configured.

​
Manage webhooks

​
List all webhooks

Retrieve all webhooks in your account. Use this to find a webhook’s id when you need to update or delete it. 
curl https://api.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>"

​
Update a webhook

Change the URL, name, events, or status of a webhook. 
curl -X PATCH https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["call.started", "call.ended", "transcript.final"] }'
FieldWhat it does
nameRename the webhook
urlChange the delivery endpoint
eventsReplace the full list of subscribed events
status"active" or "inactive" — pause delivery without deleting the webhook

​
Delete a webhook

Remove a webhook permanently. OneInbox will stop sending events to that URL immediately. 
curl -X DELETE https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>"

​
View delivery history

Retrieve the delivery-attempt log for a webhook — useful for verifying that a specific event reached your server or diagnosing failures. Returns most-recent attempt first; each row includes response_status, response_body, and error. 
curl "https://api.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"

​
API reference

Create webhook · List webhooks · Update webhook · Test delivery