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

# Subscribe to Server Events for Real-Time Notifications

> Learn how to receive real-time events from your AI Voice Agent via webhook during a call session.

In this guide, you’ll learn how to set up a webhook endpoint to receive **real-time events** from Infer’s voice infrastructure while a call is ongoing. These events allow you to track actions like tool calls, conversation turns, interruptions, transfers, and when the call ends.

**1. Create a webhook URL on your server**

To begin, you’ll need to expose an endpoint that can handle `POST` requests. This is where Infer will send structured events during a call. Your endpoint should:

* Accept `application/json`
* Respond with a 2xx status code to acknowledge receipt
* Be publicly accessible (e.g., using a service like [ngrok](https://ngrok.com) for local testing)

Example:

```bash
POST https://yourdomain.com/webhooks/voice-events
Content-Type: application/json
```

Infer will begin sending data to this URL once you configure it via the API or dashboard.

**2. Register your webhook**

Once your server is ready, you can register your webhook using the agent creation or update API by including the `event_webhook_url` field:

```json
{
  "voice_agent_id": "your-agent-id",
  "event_webhook_url": "https://yourdomain.com/webhooks/voice-events"
}
```

You can also configure this via the dashboard when creating or editing a voice agent.

**3. Understand the types of events you’ll receive**

Infer supports a wide range of server-side events. Here’s what you can expect:

<ul>
  <li>**end-call**: Triggered when the call ends. Payload includes who ended the call — the agent or the user.</li>
  <li>**transfer-call**: Triggered when a call is transferred. Includes transfer type (cold or warm) and the destination (number or agent).</li>
  <li>**tool-call**: Triggered when the agent invokes an external tool. Payload contains the function name, arguments sent, and the response.</li>
  <li>**conversation-update**: Triggered on every message exchange. Includes the role (agent/user), message content, and timestamp.</li>
  <li>**user-interrupted**: Triggered when the agent interrupts the user. Payload includes the interruption point and the partial transcript until that moment.</li>
  <li>**hang-notification**: Triggered if the agent takes too long to respond (hangs). Useful for detecting delays or fallback scenarios.</li>
</ul>

Each event payload includes:

* `type` (e.g., `"tool-call"`)
* `timestamp`
* `call_id`
* `metadata` (varies depending on event type)

**4. Example event payloads**

Here’s a sample `tool-call` event payload:

```json
{
  "type": "tool-call",
  "call_id": "abc123",
  "timestamp": "2025-04-12T14:32:00Z",
  "metadata": {
    "functionName": "getWeather",
    "arguments": { "location": "New York" },
    "response": { "temperature": "18°C", "condition": "Cloudy" }
  }
}
```

A sample `end-call` event:

```json
{
  "type": "end-call",
  "call_id": "abc123",
  "timestamp": "2025-04-12T14:35:50Z",
  "metadata": {
    "ended_by": "user"
  }
}
```

**5. Secure your webhook**

You can secure your endpoint by verifying request signatures or checking IP allowlists. Coming soon: HMAC headers for request verification.

In the meantime, ensure your endpoint is protected and does not process unauthorized requests.

**6. Use events to enhance your workflows**

Once you’re receiving events, you can:

* Store conversation logs and tool call outcomes
* Trigger downstream automations
* Alert humans in real time if something fails
* Visualize conversation timelines in your UI

Events are the key to building responsive and intelligent voice systems. Make sure to log them or pipe them into your analytics pipeline.

If you need help building or testing your webhook, reach out to [us](mailto:vaibhav@infer.so) and we’ll walk you through it!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.