webhooks schema

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Top-level webhook ingress. External HTTP callers POST /hooks/global/<hook-id> -> bead/bash/action/agent handler; node-filtered, token-authed, optionally Tailscale-Funnel-exposed.

Field path	Type	Required	Canonical description
`webhooks`	`section`	optional	Top-level webhook ingress. External HTTP callers POST /hooks/global/<hook-id> -> bead/bash/action/agent handler; node-filtered, token-authed, optionally Tailscale-Funnel-exposed.
└ `webhooks.enabled`	`bool`	optional	Whether hook ingress is enabled (default true when entries present).
└ `webhooks.token`	`string`	optional	Global bearer token (inline) accepted for any hook in this section. Mutually exclusive with token_env/token_file.
└ `webhooks.token_env`	`string`	optional	Section bearer token read from this env var at auth time (rotation-robust). Mutually exclusive with token/token_file.
└ `webhooks.token_file`	`string`	optional	Section bearer token read from this file at auth time, tilde-expanded (rotation-robust). Mutually exclusive with token/token_env.
└ `webhooks.nodes`	`list[string]`	optional	Default node filter: which daemons serve/funnel this section's hooks.
└ `webhooks.bind_host`	`string`	optional	Webhook listener bind host (default 127.0.0.1).
└ `webhooks.bind_port`	`int`	optional	Dedicated webhook listener port (the Tailscale Funnel target).
└ `webhooks.funnel`	`bool`	optional	Opt-in Tailscale Funnel exposure on the filtered nodes (default false).
└ `webhooks.max_body_bytes`	`int`	optional	Maximum request body size in bytes (default 1 MiB).
└ `webhooks.entries`	`map[string, map]`	optional	Hooks keyed by <hook-id> (the URL path segment).
└ `webhooks.entries.<hook-id>`	`map`	optional	A single webhook served at /hooks/<scope>/<hook-id>.
└ `webhooks.entries.<hook-id>.type`	`string`	required	Handler type: bead \| bash \| action \| agent.
└ `webhooks.entries.<hook-id>.token`	`string`	optional	Per-hook bearer token (inline; accepted in addition to the section token). Mutually exclusive with token_env/token_file.
└ `webhooks.entries.<hook-id>.token_env`	`string`	optional	Per-hook bearer token read from this env var at auth time (rotation-robust). Mutually exclusive with token/token_file.
└ `webhooks.entries.<hook-id>.token_file`	`string`	optional	Per-hook bearer token read from this file at auth time, tilde-expanded (rotation-robust). Mutually exclusive with token/token_env.
└ `webhooks.entries.<hook-id>.nodes`	`list[string]`	optional	Per-hook node filter (overrides the section nodes).
└ `webhooks.entries.<hook-id>.description`	`string`	optional	Human-readable description.
└ `webhooks.entries.<hook-id>.command`	`string`	optional	type=bash: shell command (sh -c) with the body in $CACO_HOOK_BODY.
└ `webhooks.entries.<hook-id>.action`	`string`	optional	type=action: name of a configured action to run.
└ `webhooks.entries.<hook-id>.profile`	`string`	optional	type=agent: profile of the bead-creator agent to dispatch.
└ `webhooks.entries.<hook-id>.bead`	`map`	optional	type=bead: defaults applied to the created bead.
└ `webhooks.entries.<hook-id>.bead.project`	`string`	optional	Target project for the created bead (defaults to the hook scope project).
└ `webhooks.entries.<hook-id>.bead.title`	`string`	optional	Literal bead title.
└ `webhooks.entries.<hook-id>.bead.title_prefix`	`string`	optional	Prefix prepended to the resolved title.
└ `webhooks.entries.<hook-id>.bead.title_from`	`string`	optional	Top-level JSON body field to take the title from.
└ `webhooks.entries.<hook-id>.bead.labels`	`list[string]`	optional	Labels applied to the created bead.
└ `webhooks.entries.<hook-id>.bead.type`	`string`	optional	Bead type (task/bug/feature/epic). Defaults to task.
└ `webhooks.entries.<hook-id>.bead.priority`	`int`	optional	Bead priority 0-4.
└ `webhooks.entries.<hook-id>.timeout_secs`	`int`	optional	Handler timeout in seconds (bash/action). Default 300.