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

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.