Pre-call webhooks for custom functions

A custom function can fire a pre-call webhook — a notification sent to a URL of your choice before the tool’s main API call runs. A common use case is a tool that transfers the call, where your system needs to receive the transfer reason before the transfer happens.

The pre-call webhook is fire-and-forget. A slow or failing webhook endpoint never blocks or fails the function call itself.

The built-in Transfer Call tool supports the same pre-call webhook fields, fired before the transfer happens.

How it works

LLM decides to call the tool

The LLM produces the arguments for your custom function as usual.

Bolna fires the pre-call webhook

If the tool has a pre_call_webhook_param configured, Bolna first POSTs the pre-call webhook to the resolved URL.

The main API call runs

The tool’s main function call then executes exactly as it normally would.

Configuring the webhook body

pre_call_webhook_param is a JSON template that is completely independent from the tool’s main param. You can reference any argument the LLM produced for the tool using the same %(field)s substitution syntax used by param. Static values are passed through as-is.

{
  "name": "transfer_support",
  "description": "Transfers the call to a support agent when the caller asks for a human or has an issue the agent cannot resolve.",
  "parameters": {
    "type": "object",
    "properties": {
      "reason": {
        "type": "string",
        "description": "Why the caller wants a transfer"
      }
    },
    "required": ["reason"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "url": "https://your-api.com/transfer",
    "param": {
      "reason": "%(reason)s"
    },
    "pre_call_webhook_url": "https://your-api.com/pre-transfer-hook",
    "pre_call_webhook_param": {
      "transfer_reason": "%(reason)s",
      "channel": "voice"
    }
  }
}

In the example above, %(reason)s is replaced with the LLM’s argument for this tool call, while "channel": "voice" is a static value passed through unchanged.

What your endpoint receives

The webhook body is the same execution record you receive on the post-call execution webhook (execution id, agent id, telephony details, status, etc.), merged with the fields from your pre_call_webhook_param:

{
  "id": "<execution_id>",
  "agent_id": "<agent_id>",
  "status": "in-progress",
  "telephony_data": { "...": "..." },
  "...": "...",

  "transfer_reason": "customer asked for billing",
  "channel": "voice"
}

Because the call is still in progress when the pre-call webhook fires, fields that are only finalized at call end (transcript, cost, summary) won’t be complete yet.

URL resolution rules

`pre_call_webhook_param`	`pre_call_webhook_url`	Result
Set	Set	Webhook sent to the tool’s `pre_call_webhook_url`.
Set	Not set	Webhook sent to the agent-level Webhook URL (the same URL used for post-call execution webhooks).
Not set	Set or not set	No pre-call webhook fires.

pre_call_webhook_param is the master switch. If it is not set, no pre-call webhook fires — even if pre_call_webhook_url is configured. The agent’s normal post-call webhook is unaffected.

Agent-level URL fallback: when pre_call_webhook_param is set without a pre_call_webhook_url, the pre-call webhook is sent to your agent’s configured Webhook URL. If you already use that endpoint for post-call execution webhooks, it will now also receive pre-call webhooks. Distinguish them by the in-progress status and the extra fields from your pre_call_webhook_param.

UI configuration

In the agent dashboard, the custom tool configuration (on the Tools Tab) has two optional inputs that map to these fields:

Pre-call webhook URL — the endpoint to notify (pre_call_webhook_url).
Pre-call webhook parameters — the JSON body template with %(field)s substitution (pre_call_webhook_param).

Both save with the tool and round-trip on edit.

Build

Deploy

Monitor

Go live

Pre-call webhooks for custom functions

How it works

Configuring the webhook body

What your endpoint receives

URL resolution rules

UI configuration

​How it works

​Configuring the webhook body

​What your endpoint receives

​URL resolution rules

​UI configuration

How it works

Configuring the webhook body

What your endpoint receives

URL resolution rules

UI configuration