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

# Webhook tools

> Define a reviewed HTTP action, configure its request schema and credential references, and inspect the saved dashboard tool.

A webhook tool describes an HTTP request to a service you control or have permission to use. Start with one clearly defined action and the service's actual request and response contract.

<Note>
  Use the authenticated dashboard to manage tools; personal API keys are currently rejected for these operations. Saving a webhook tool does not demonstrate request delivery, retries, or successful execution during a conversation.
</Note>

## Define the request

<Frame caption="Recording pending: define and inspect a webhook tool. Follow the written guide below.">
  <img src="https://mintcdn.com/threetonelabs-c2efc9c8/RV32i5440UZIaFHA/images/tutorials/recording-pending.webp?fit=max&auto=format&n=RV32i5440UZIaFHA&q=85&s=55f66d2eef49d8c92c9ac46f84bace35" alt="Recording pending for webhook tool authoring and read-back. No playable video is available yet." width="1600" height="900" className="w-full h-auto aspect-video" loading="lazy" noZoom data-path="images/tutorials/recording-pending.webp" />
</Frame>

<Steps>
  <Step title="Open the webhook form">
    Open [Tools](https://threetone.in/app/agents/tools) and choose **Add webhook tool**. Give the action a precise name and description. Prefer a read-only lookup for initial integration planning.
  </Step>

  <Step title="Match the service contract">
    Review the URL, method, path parameters, query parameters, and request body. A path placeholder such as `{record_id}` needs a matching entry in `path_params_schema`.
  </Step>

  <Step title="Review authentication and returned data">
    Use supported [auth connections](/agents-platform/configure/authentication/auth-connections) or [secret references](/agents-platform/configure/authentication/secrets). Keep credentials out of the tool description and model-supplied arguments.

    Define the smallest response the task needs. The service must validate arguments and authorize access independently of the prompt.
  </Step>

  <Step title="Save and inspect">
    Select **Add tool**, reopen the resource, and check the persisted request definition. Attach the reviewed tool through the agent's [Tools page](/agents-platform/configure/tools/overview), then inspect its ID in the agent draft.
  </Step>
</Steps>

## Request fields

These fields are under the webhook tool's `api_schema`.

| Field | Configuration |
| - | - |
| `url` | The intended service URL. |
| `method` | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. |
| `path_params_schema`, `query_params_schema` | Input definitions matched to the service contract. |
| `request_body_schema`, `response_body_schema` | Optional body and response definitions. |
| `request_headers`, `auth_connection` | Supported header and credential configuration. |
| `content_type` | `application/json` or `application/x-www-form-urlencoded`. |
| `response_filter` | Requested filtering of returned content; verify actual behavior before relying on it. |

The outer tool configuration also includes `follow_redirects` and `follow_redirects_allowed_domains`. Enabling redirects requires a nonempty allowed-domain list. Review it with the endpoint operator and the current schema. A saved setting is not proof of network-policy enforcement.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is this the same as an event webhook?" id="faq-webhook-tools-events">
    No. A webhook tool describes an agent-requested HTTP action. Notifications about product events are a separate feature; this guide does not establish event delivery or signature verification.
  </Accordion>

  <Accordion title="How should I prepare a write operation?" id="faq-webhook-tools-writes">
    Define authorization, required confirmation, duplicate-request handling, and a way to inspect an uncertain result in your service. Do not infer those protections from a tool description.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.