> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time events from OneInbox on your server — no polling required.

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

```bash theme={null}
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"]
  }'
```

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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"] }'
```

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

```bash theme={null}
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`.

```bash theme={null}
curl "https://api.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"
```

***

## API reference

[Create webhook](/api-reference/webhooks/create-webhook) · [List webhooks](/api-reference/webhooks/list-webhooks) · [Update webhook](/api-reference/webhooks/update-webhook) · [Test delivery](/api-reference/webhooks/test-webhook-delivery)