Skip to main content
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 for local testing)
Example:
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:
{
  "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:
  • end-call: Triggered when the call ends. Payload includes who ended the call — the agent or the user.
  • transfer-call: Triggered when a call is transferred. Includes transfer type (cold or warm) and the destination (number or agent).
  • tool-call: Triggered when the agent invokes an external tool. Payload contains the function name, arguments sent, and the response.
  • conversation-update: Triggered on every message exchange. Includes the role (agent/user), message content, and timestamp.
  • user-interrupted: Triggered when the agent interrupts the user. Payload includes the interruption point and the partial transcript until that moment.
  • hang-notification: Triggered if the agent takes too long to respond (hangs). Useful for detecting delays or fallback scenarios.
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:
{
  "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:
{
  "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 and we’ll walk you through it!