***

title: Inbound Webhook
slug: inbound-webhook-api
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.synthflow.ai/llms.txt. For full documentation content, see https://docs.synthflow.ai/llms-full.txt.

<div>
  <iframe src="https://player.vimeo.com/video/1101493486?h=7165ddc192&badge=0&autopause=0&player_id=0&app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media; web-share" title="Inbound Webhook Synthflow" />
</div>

You can intercept, reroute and decline every incoming call with inbound call webhooks.

You will receive a JSON payload (`event: "call_inbound"`) within 10 seconds after a call was initiated. Your endpoint will need to respond with an updated `call_inbound` object to assign an agent to the call or update the metadata.

### What to expect

* If your endpoint responds with an empty call\_inbound object (e.g. `{}` with no agent assignment), the call will be disconnected.
* If you return `override_model_id` as an empty string (`""`), the call continues with the agent that received the call (no reroute, no disconnect).
* If your endpoint doesn't respond within timeout, the call is put on hold. Up to 3 more requests will be sent. If all these attempts fail, the call will be rerouted to the `default_agent` you specified. If you did not specify a `default_agent`, the call will be disconnected.

## Requests

Every inbound call will generate and send a JSON in this format:

```json
{
  "event": "call_inbound",
  "call_inbound": {
    "model_id": "optional_agent_id", // the default agent, if preconfigured by you
    "from_number": "+12137771234", // the caller
    "to_number": "+12137771235" // the receiving number
  }
}
```

## Responses

Your endpoint needs to respond with an updated call\_inbound object.

```json
{
  "call_inbound": {
    "override_model_id": "agent_67890", // reroute to another agent; use "" to keep the default agent
    "custom_variables": { // context and data for further call flow
      "customer_name": "John Doe" 
    },
    "metadata": { // metadata for post-call analysis
      "session_id": "abc123"
    }
  }
}
```