Webhooks

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-tokyo.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

Event	When it fires
`call.started`	Call connects and the agent begins the session
`call.ended`	Call ends — agent or caller hung up
`call.analyzed`	AI analysis (summary, outcome) is ready after the call
`call.failed`	Call failed to connect
`call.recording.available`	Call recording is ready and accessible
`transcript.partial`	Partial transcript update during an active call
`transcript.final`	Full 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-tokyo.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-tokyo.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-tokyo.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-tokyo.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["call.started", "call.ended", "transcript.final"] }'

Field	What it does
`name`	Rename the webhook
`url`	Change the delivery endpoint
`events`	Replace 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-tokyo.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-tokyo.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"

API reference

Create webhook · List webhooks · Update webhook · Test delivery

Get started

Make calls

Configure your agent

Monitor & integrate

Core concepts

How webhooks work

Create a webhook

Supported events

Event payloads

`call.started`

`call.ended`

`call.analyzed`

`call.failed`

`call.recording.available`

`transcript.partial`

`transcript.final`

Test a webhook

Per-call webhook override

Manage webhooks

List all webhooks

Update a webhook

Delete a webhook

View delivery history

API reference

​How webhooks work

​Create a webhook

​Supported events

​Event payloads

​call.started

​call.ended

​call.analyzed

​call.failed

​call.recording.available

​transcript.partial

​transcript.final

​Test a webhook

​Per-call webhook override

​Manage webhooks

​List all webhooks

​Update a webhook

​Delete a webhook

​View delivery history

​API reference

How webhooks work

Create a webhook

Supported events

Event payloads

`call.started`

`call.ended`

`call.analyzed`

`call.failed`

`call.recording.available`

`transcript.partial`

`transcript.final`

Test a webhook

Per-call webhook override

Manage webhooks

List all webhooks

Update a webhook

Delete a webhook

View delivery history

API reference