Webhook tools - Cartesia Docs

Webhook tools connect an agent to your systems. When the model calls one, Cartesia sends an HTTP request to your endpoint and returns the response to the model.

Define a webhook tool

Send this body to POST /v1/agents/tools. Replace the example URL and credentials with your own.

POST /v1/agents/tools

{
  "type": "webhook",
  "name": "lookup_order",
  "description": "Looks up an order by its number. Use it when the caller asks about order status or delivery.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "response_timeout_secs": 20,
  "api_schema": {
    "url": "https://api.acme.com/orders/{order_id}",
    "method": "GET",
    "path_params_schema": {
      "order_id": {
        "type": "string",
        "description": "Order number provided by the caller."
      }
    },
    "request_headers": {
      "X-Tenant": "acme"
    },
    "authentication": {
      "mode": "bearer",
      "token": {
        "type": "secret",
        "secret_value": "sk_live_..."
      }
    }
  }
}

Attach the returned tool ID through config.tools. See Tools for the shared execution settings.

Request schema

api_schema.url must use HTTPS, and requests to private and internal network ranges are blocked. Supported methods are GET, POST, PUT, PATCH, and DELETE.

path_params_schema fills placeholders such as {order_id}. Each path parameter is required and may be a string, integer, or number.
query_params_schema describes query parameters with properties and an optional required list.
request_body_schema describes a JSON object for POST, PUT, or PATCH. Body properties may be nested.

Choose how each parameter gets its value:

Value source	Configuration
Model	Use `description` to explain what to provide, and optionally `enum` to constrain values
Fixed value	Set `constant_value`, such as a tenant ID or API version
Dynamic variable	Set `dynamic_variable` to the variable’s name

Parameter descriptions tell the model what value to provide. Use constant_value for a value the model should not choose, such as an API version. Use dynamic_variable values for per-customer context or values fetched at runtime. For example, this tool sends the current customer_id with each request:

POST /v1/agents/tools

{
  "type": "webhook",
  "name": "track_order",
  "description": "Track an order using the caller's order number and customer account.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "api_schema": {
    "url": "https://api.example.com/orders/track",
    "method": "POST",
    "request_body_schema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "Order number provided by the caller."
        },
        "customer_id": { "type": "string", "dynamic_variable": "customer_id" },
        "region": { "type": "string", "constant_value": "us-east" }
      },
      "required": ["order_id"]
    }
  }
}

Dynamic variables can fill string, number, and boolean fields, including fields within an object. They cannot fill an entire object, a list, or fields within a list. Tool and parameter descriptions can also use dynamic variables. For example, add Last known status: {{order_status}} to the tool description so the model can see the value too.

Headers and authentication

api_schema.request_headers accepts strings, secrets, and dynamic variables. Add headers with PATCH /v1/agents/tools/{tool_id}, using your tool ID and API credential:

PATCH /v1/agents/tools/{tool_id}

{
  "api_schema": {
    "request_headers": {
      "X-Tenant": "acme",
      "X-Api-Key": {
        "type": "secret",
        "secret_value": "..."
      },
      "X-Customer-Id": {
        "type": "dynamic_variable",
        "name": "customer_id"
      }
    }
  }
}

authentication adds credentials to the Authorization header at request time. bearer sends Authorization: Bearer <token>, and basic_auth sends Authorization: Basic <base64(username:password)>. Do not also set Authorization in request_headers. The API never returns saved secret values. When updating a tool, omitted headers and authentication stay unchanged. If you include an existing secret field, use { "type": "secret" } without secret_value to keep its value. To remove a header, set that header to null inside api_schema.request_headers. To remove authentication, set api_schema.authentication to null. Cartesia reserves transport headers that it manages itself. Header names must be unique, regardless of capitalization.

Responses and timeouts

The response body becomes the tool result. Keep it focused on the data the model needs. Use assignments to save response fields as dynamic variables. For a response such as {"order": {"id": "A-1001", "status": "shipped"}}, the assignments below save the order ID and status. Configure them in the tool’s side panel in the Playground or with PATCH /v1/agents/tools/{tool_id}:

PATCH /v1/agents/tools/{tool_id}

{
  "assignments": [
    { "dynamic_variable": "order_status", "value_path": "order.status" },
    { "dynamic_variable": "order_id", "value_path": "order.id" }
  ]
}

Assignments apply after a successful JSON response. A failed request, missing field, or null value leaves the previous variable value unchanged. Objects and lists are saved as JSON text. The request times out after response_timeout_secs, which defaults to 20 seconds. Use execution_mode: "async" for requests that do not need to block the current turn.

​Define a webhook tool

​Request schema

​Headers and authentication

​Responses and timeouts

Define a webhook tool

Request schema

Headers and authentication

Responses and timeouts