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

# Callbacks

> Callbacks are HTTP POST requests Vobiz sends to your server when call, recording, conference, and message events occur - enabling real-time event handling.

<Info>
  **What are callbacks?** When events occur in your Vobiz account (a call completing, a recording finishing, a conference ending), Vobiz automatically sends HTTP POST requests to your server with details about the event. This lets your application react to events in real time without polling.
</Info>

## How Callbacks Work

<Steps>
  <Step title="Configure Callback URL">
    You provide a callback URL when creating resources (applications, trunks, calls, etc.).
  </Step>

  <Step title="Event Occurs">
    An event happens in your account (call ends, recording completes, etc.).
  </Step>

  <Step title="Vobiz Sends HTTP POST">
    Vobiz sends an HTTP POST request to your callback URL with event details.
  </Step>

  <Step title="Your Server Responds">
    Your server processes the callback and responds with HTTP 200 OK.
  </Step>
</Steps>

### Example Callback Request

When a call ends, Vobiz sends a POST request to your callback URL:

```http POST Request to Your Callback URL theme={null}
POST /webhooks/call-status HTTP/1.1
Host: your-domain.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Vobiz-Webhook/1.0

{
  "Event": "Hangup",
  "CallUUID": "550e8400-e29b-41d4-a716-446655440000",
  "From": "+14155551234",
  "To": "+14155555678",
  "Status": "completed",
  "Duration": 125,
  "StartTime": "2025-10-30T10:30:00Z",
  "EndTime": "2025-10-30T10:32:05Z",
  "Direction": "outbound",
  "auth_id": "{auth_id}"
}
```

### Example Server Response

Your server should respond with HTTP 200 to acknowledge receipt:

```http Your Server Response theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}
```

## Callback Events

| Event Type            | Description            | When It's Sent                                    |
| --------------------- | ---------------------- | ------------------------------------------------- |
| `Ring`                | Call is ringing        | When outbound call starts ringing (via `/answer`) |
| `StartApp`            | Call was answered      | When the called party answers (via `/answer`)     |
| `Hangup`              | Call has ended         | When call completes (via `/answer`)               |
| `recording.completed` | Recording is ready     | When recording finishes processing                |
| `conference.started`  | Conference has started | When first participant joins                      |
| `conference.ended`    | Conference has ended   | When last participant leaves                      |

## Callback Parameters

### Standard Parameters

All callback requests include these standard parameters:

| Parameter   | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| `Event`     | string | Event type identifier (e.g., Ring, StartApp, Hangup) |
| `timestamp` | string | ISO 8601 timestamp of when event occurred            |
| `auth_id`   | string | Your Vobiz account identifier                        |
| `CallUUID`  | string | Unique identifier for the call                       |

## Security Considerations

### Always Use HTTPS

<Warning>
  **Important:** Only use HTTPS URLs for callback endpoints. HTTP URLs are not supported for security reasons.
</Warning>

### Verify Callback Source

Every callback Vobiz sends includes HMAC-SHA256 signatures in the request headers (`X-Vobiz-Signature-V2`, `X-Vobiz-Signature-V3`, and their multi-account variants). Validate these signatures to confirm the request genuinely came from Vobiz and was not tampered with.

<Card title="Validating Callbacks" icon="shield-check" href="/concepts/validating-callbacks">
  Full validation guide with code examples in Python, Node.js, Go, and Ruby.
</Card>

## Best Practices

* **Respond quickly** - Return HTTP 200 within 3 seconds. If processing takes longer, queue the callback for async processing and respond immediately.
* **Handle retries** - Vobiz will retry failed callbacks (non-200 responses) up to 3 times with exponential backoff. Make your callback handlers idempotent to handle duplicate deliveries.
* **Log everything** - Log all incoming callbacks with full payload for debugging. Include timestamps, event types, and processing results.
* **Monitor callback health** - Track callback success/failure rates, response times, and set up alerts for failures. Monitor for missing callbacks as a sign of delivery issues.
* **Use separate endpoints** - Consider using different callback URLs for different event types or resources to simplify routing and processing logic.