> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook tools

> Let an agent call an HTTPS endpoint on your server.

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

```json theme={null}
{
  "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`](/api-reference/agents/tools/create), then attach its ID through `config.tools`. See [Tools](/agents/tools#execution-settings) 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:

```json theme={null}
{
  "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.