Replace the workspace's hook rules (owner only) [write]
Changed onThe body is the whole ordered list (at most 20); the order is the order of evaluation. A rule sent with the id of an existing rule keeps it. Points: session.start (a session is about to be created), tool.call (a capability call, a call to a connected app, or a tool the gateway runs for a session reached the platform), spend (a session's consumed cost reached match.amount, whole US cents; read when a turn ends and at a capability call, once per session), turn.end (a turn ended). Actions: notify delivers a signed event (hook.session_start, hook.tool_call, hook.spend, hook.turn_end) to webhook_id, one of the workspace's webhook endpoints, whatever events that endpoint subscribed to; never a URL. block at session.start refuses the session with 403 blocked_by_hook_rule; at tool.call it refuses the call with capability_denied (reason: hook_rule). require_approval at tool.call asks the session's owner exactly as an ask capability policy does, and an answer covers one call. require_approval at session.start creates the session waiting: it has no sandbox and takes no turn (409 start_not_approved), and its task carries an approval request for the person who created it, answered confirm or decline through POST /tasks/{id}/requests/{request_id}/answer. Approved, it starts with what it was created with; declined, it is archived, never runs and is charged nothing. A session started in a way that cannot wait (a helper, a product run, a handoff) is refused with 403 blocked_by_hook_rule. The most restrictive of the matching rules and the capability policies wins. Refused with 400 and the reason: block and require_approval at spend and at turn.end. match narrows a rule: {agent_id} at session.start and turn.end, {capability_id} or {connector_app} (the slug of a connected app), not both, at tool.call; omitted, the rule applies to all. A notify rule that cannot be delivered never affects the session. 403 not_enabled where hook rules are not turned on; 503 not_migrated before the tables exist.
Request
- Base URLhttps://api.agentsky.dev/v1
- URLhttps://api.agentsky.dev/v1/hook_rules
- AuthHTTP bearer
Request body
Response
OK
Changes
- info
endpoint added
- info