When a Webhook tool (custom_webhook) is called, Phonic makes an HTTP request to the endpoint you configured. Webhook tools work whether you run a conversation via Webhook or via WebSocket.

See Tool Definition for the shared name, description, and parameters fields, and Tool Behavior Configuration for the behavior toggles.

Endpoint

In the dashboard, under Endpoint you set:

• Method (endpoint_method) — GET or POST.
• URL (endpoint_url) — must be a publicly routable URL.
• Headers (endpoint_headers) — optional, e.g. an Authorization header.
• Timeout (endpoint_timeout_ms) — default 5000 ms, between 1000 and 180000 ms.

All parameters of a GET Webhook tool go in the query string. For POST Webhook tools, each parameter has a location (request_body or query_string).

Call Context Information

When a Webhook tool is used with an Agent making calls on Phonic’s infrastructure, call context (call_info) is automatically included in the request:

• conversation_id: The unique identifier for the current conversation
• from_phone_number: The caller’s phone number (when available)
• to_phone_number: The destination phone number (when available)

GET Webhook Request Format

For GET Webhook tools, call context and parameters are included as query string parameters:

GET /your-endpoint?city=Seattle&temperature_unit=celsius&conversation_id=conv_abc123&from_phone_number=%2B15551234567&to_phone_number=%2B15557654321

• Tool parameters: query string parameters (e.g., city, temperature_unit)
• Call context: individual query string parameters (conversation_id, from_phone_number, to_phone_number)

POST Webhook Request Format

For POST Webhook tools, the request body includes a call_info object along with your tool parameters:

1
{
2
    "call_info": {
3
        "conversation_id": "conv_abc123",
4
        "from_phone_number": "+15551234567",
5
        "to_phone_number": "+15557654321"
6
    },
7
    "city": "Seattle",
8
    "temperature_unit": "celsius"
9
}

• Tool parameters: at the root level of the JSON body (e.g., city, temperature_unit)
• Call context: in a nested call_info object

TypeScript Interface Examples

For GET Webhooks:

1
// Query parameters your endpoint will receive
2
interface GetWeatherWebhookParams {
3
  // Your tool parameters
4
  city: string;
5
  temperature_unit?: string;
6
7
  // Call context (automatically added by Phonic)
8
  conversation_id: string;
9
  from_phone_number?: string;
10
  to_phone_number?: string;
11
}

For POST Webhooks:

1
// Request body your endpoint will receive
2
interface PostWeatherWebhookBody {
3
  // Call context (automatically added by Phonic)
4
  call_info: {
5
    conversation_id: string;
6
    from_phone_number?: string;
7
    to_phone_number?: string;
8
  };
9
10
  // Your tool parameters
11
  city: string;
12
  temperature_unit?: string;
13
}

Creating a Webhook Tool

1
import { config } from "dotenv";
2
import { PhonicClient } from "phonic";
3
4
config({ path: ".env.local" });
5
6
const apiKey = process.env.PHONIC_API_KEY;
7
const client = new PhonicClient({ apiKey });
8
9
async function createTool() {
10
  await client.tools.create({
11
    name: "add_destination",
12
    description:
13
      "Add a destination to the list when the user indicates they will visit it.",
14
    type: "custom_webhook",
15
    execution_mode: "sync",
16
    endpoint_method: "POST",
17
    endpoint_url: `https://${NGROK_URL.replace("https://", "")}/webhooks/add-destination`,
18
    endpoint_timeout_ms: 7000,
19
    parameters: [
20
      {
21
        name: "destination_name",
22
        description: "The name of the destination",
23
        is_required: true,
24
        type: "string",
25
      },
26
    ],
27
  });
28
}
29
30
createTool()