feat(hooks): add agentId support to webhook mappings (#13672)

* feat(hooks): add agentId support to webhook mappings

Allow webhook mappings to route hook runs to a specific agent via
the new `agentId` field. This enables lightweight agents with minimal
bootstrap files to handle webhooks, reducing token cost per hook run.

The agentId is threaded through:
- HookMappingConfig (config type + zod schema)
- HookMappingResolved + HookAction (mapping types)
- normalizeHookMapping + buildActionFromMapping (mapping logic)
- mergeAction (transform override support)
- HookAgentPayload + normalizeAgentPayload (direct /hooks/agent endpoint)
- dispatchAgentHook → CronJob.agentId (server dispatch)

The existing runCronIsolatedAgentTurn already supports agentId on
CronJob — this change simply wires it through from webhook mappings.

Usage in config:
  hooks.mappings[].agentId = "my-agent"

Usage via POST /hooks/agent:
  { "message": "...", "agentId": "my-agent" }

Includes tests for mapping passthrough and payload normalization.
Includes doc updates for webhook.md.

* fix(hooks): enforce webhook agent routing policy + docs/changelog updates (#13672) (thanks @BillChirico)

* fix(hooks): harden explicit agent allowlist semantics (#13672) (thanks @BillChirico)

---------

Co-authored-by: Pip <pip@openclaw.ai>
Co-authored-by: Gustavo Madeira Santana <gumadeiras@gmail.com>
This commit is contained in:
Bill Chirico
2026-02-10 19:23:58 -05:00
committed by GitHub
parent 45488e4ec9
commit ca629296c6
13 changed files with 448 additions and 2 deletions

View File

@@ -32,6 +32,7 @@ export function createGatewayHooksRequestHandler(params: {
const dispatchAgentHook = (value: {
message: string;
name: string;
agentId?: string;
wakeMode: "now" | "next-heartbeat";
sessionKey: string;
deliver: boolean;
@@ -48,6 +49,7 @@ export function createGatewayHooksRequestHandler(params: {
const now = Date.now();
const job: CronJob = {
id: jobId,
agentId: value.agentId,
name: value.name,
enabled: true,
createdAtMs: now,