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", "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
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",
  "analysis": {
    "outcome": "Appointment Booked",
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  }
}

​
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, or the list of events a webhook listens for. For example, update the events array to start receiving transcript.final in addition to call.ended. 
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"] }'

​
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>"

​
API reference

Create webhook · List webhooks · Update webhook · Test delivery