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

# hooks

> Lifecycle webhooks fired at key moments (pre/post query, on tool call, on handoff). A Business-tier capability; for an all-plan equivalent use a callback…

# `hooks` — Hooks

Lifecycle webhooks fired at key moments (pre/post query, on tool call, on handoff). A Business-tier capability; for an all-plan equivalent use a `callback` rule.

**Section key** `hooks` · **Shape** array · **Tier** Business only (not in the free trial)\
**Edit in the dashboard:** [Hooks page](/sidebar-menu/hooks)

> List of lifecycle hook definitions.

## Fields (per item)

| Field            | Required | Type    | Allowed values / constraints                                                                                                                                                                                                                                                                             | Default | Description                                                                                                                                                                                                                                        |
| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | **yes**  | string  | —                                                                                                                                                                                                                                                                                                        | —       | Identifier for this hook.                                                                                                                                                                                                                          |
| `event`          | **yes**  | enum    | one of `on_user_message`, `pre_query`, `post_query`, `on_error`, `pre_tool_call`, `post_tool_call`, `on_handoff`, `on_alert`, `on_conversation_start`, `on_conversation_end`, `on_rate_limit`, `on_handoff_resolved`, `on_goal_complete`, `on_payment`, `on_inbound`, `on_schedule_run`, `on_feed_match` | —       | When the hook fires.                                                                                                                                                                                                                               |
| `enabled`        | no       | boolean | —                                                                                                                                                                                                                                                                                                        | —       | When false, the hook is registered but will not fire.                                                                                                                                                                                              |
| `collapsed`      | no       | boolean | —                                                                                                                                                                                                                                                                                                        | —       | UI hint — start this entry collapsed in the dashboard.                                                                                                                                                                                             |
| `filter`         | no       | object  | —                                                                                                                                                                                                                                                                                                        | —       | Optional predicate object (e.g. match a tool name).                                                                                                                                                                                                |
| `action`         | **yes**  | object  | —                                                                                                                                                                                                                                                                                                        | —       | HTTP callback configuration fired when the hook matches. Contains url (required), method, headers, timeout\_ms, and blocking flag. The webhook receives an event payload and can return verdicts to block/modify the chat flow. Item fields below. |
| `tool_selection` | no       | object  | —                                                                                                                                                                                                                                                                                                        | —       | Optional tool-list narrowing applied for this hook's invocation. Item fields below.                                                                                                                                                                |

### `action` fields

HTTP callback configuration fired when the hook matches. Contains url (required), method, headers, timeout\_ms, and blocking flag. The webhook receives an event payload and can return verdicts to block/modify the chat flow.

| Field        | Required | Type            | Allowed values / constraints | Default | Description                                                                                                                                                         |
| ------------ | -------- | --------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`        | no       | string          | —                            | —       | HTTP callback URL.                                                                                                                                                  |
| `method`     | no       | enum            | one of `GET`, `POST`         | —       | HTTP method for the webhook request. GET or POST (defaults to POST). Determines whether the payload is sent in the request body (POST) or omitted (GET).            |
| `headers`    | no       | array of object | —                            | —       | Custom HTTP headers sent with the webhook request. Array of \{key, value} objects; empty key/value pairs are skipped. Useful for authentication or routing headers. |
| `timeout_ms` | no       | number          | —                            | —       | Request timeout in milliseconds. Clamped to 500–60000 (defaults to 5000). When exceeded, the request is aborted; blocking hooks become non-fatal errors.            |
| `blocking`   | no       | boolean         | —                            | —       | When true, the agent waits for the hook response before continuing. When false (default), the hook fires and-forget.                                                |

### `tool_selection` fields

Optional tool-list narrowing applied for this hook's invocation.

| Field      | Required | Type            | Allowed values / constraints | Default | Description                                                                                                                                                                                    |
| ---------- | -------- | --------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`     | no       | enum            | one of `all`, `specific`     | —       | Scope limiter for tool-specific hooks (pre\_tool\_call/post\_tool\_call). 'all' = applies to every tool call; 'specific' = applies only to tools listed in tool\_ids. Defaults to 'all'.       |
| `tool_ids` | no       | array of string | —                            | —       | Stable tool identifiers this hook applies to when mode='specific' (e.g., 'internal:web\_search', 'my\_custom\_tool'). Empty when mode='all'. Tool IDs come from the tools-aggregator registry. |