Webhook tools - Cartesia Docs

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

Define a webhook tool

{
  "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_..."
      }
    }
  }
}

Create the tool with POST /v1/agents/tools, then attach its 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.

Parameter descriptions tell the model what value to provide. Use enum to constrain a value. Use constant_value for a value the model must not choose, such as a tenant ID or API version.

Headers and authentication

request_headers accepts literal strings and write-only secrets:

{
  "request_headers": {
    "X-Tenant": "acme",
    "X-Api-Key": {
      "type": "secret",
      "secret_value": "..."
    }
  }
}

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. Secret values are write-only and never returned. To keep an existing secret when you update a tool, send its field as { "type": "secret" } without secret_value. Omitting the field removes that credential. To remove authentication entirely, omit authentication from the api_schema you send. 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. Return only the data the model needs; Cartesia truncates response bodies after 4 KiB. 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