#9800: feat(hooks): allow webhook mappings to route to specific agents via a…
gateway
stale
…gentId
Add agentId support to webhook hook mappings, enabling multi-agent webhook routing. The agentId can be set either statically in the mapping config or dynamically via transform return values.
Changes:
- Add agentId to HookMappingConfig type and Zod validation schema
- Add agentId to HookMappingResolved, HookAction, and HookTransformResult types
- Thread agentId through normalizeHookMapping, buildActionFromMapping, mergeAction, dispatchAgentHook, and into runCronIsolatedAgentTurn
- Support template rendering in agentId (e.g. '{{payload.inbox}}')
- Transform agentId overrides mapping-level agentId
Closes #9130
## 🤖 AI-Assisted
This PR was authored with AI assistance (Claude/OpenClaw).
- **Degree of testing:** Fully tested — 6 new unit tests, full suite (5207 tests) passing, build + lint clean
- **Understanding:** The author understands all changes — agentId is threaded as an optional string through the existing hooks mapping pipeline, ultimately passed to runCronIsolatedAgentTurn which already supports the agentId parameter
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds `agentId` support to webhook hook mappings so a mapping (or its transform) can route an incoming hook to a specific agent. The change extends the hooks config types + Zod schema, threads `agentId` through mapping normalization/action building/merging, and passes it through the gateway HTTP hook handler into `runCronIsolatedAgentTurn`. Tests were added to cover mapping-level, transform-level, and template-rendered `agentId` behaviors.
Within the codebase, this integrates with the existing hooks mapping pipeline (`src/gateway/hooks-mapping.ts`) and the gateway’s hooks HTTP server (`src/gateway/server-http.ts` / `src/gateway/server/hooks.ts`) by ultimately selecting an agent in the cron isolated agent runner.
<h3>Confidence Score: 4/5</h3>
- This PR is generally safe to merge, but there are a couple of behavior gaps around agentId handling that should be resolved to match the intended feature surface.
- The changes are small and well-threaded with tests for mapping/transform/template routing. The main remaining concerns are (1) `agentId` isn’t actually accepted by the direct `/hooks/agent` endpoint despite being threaded into the dispatcher, and (2) transforms can’t intentionally clear a mapping-provided agentId due to nullish-coalescing merge semantics.
- src/gateway/server-http.ts, src/gateway/hooks-mapping.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#10663: feat(hooks): add agentId support for webhook routing
by nityatrish · 2026-02-06
93.8%
#10383: feat(hooks): add agentId to hook mappings
by quentintou · 2026-02-06
90.7%
#7846: feat: add agentId param to webhook agent endpoint
by Bre77 · 2026-02-03
86.6%
#7301: fix(hooks): use resolveAgentIdFromSessionKey instead of split(":")[0]
by tsukhani · 2026-02-02
79.8%
#6630: feat(hooks): add agent:turn_start and agent:turn_end lifecycle events
by drdigital13 · 2026-02-01
75.6%
#12635: Gateway: add inbound webhook dispatch framework
by jhs129 · 2026-02-09
74.0%
#7771: Hooks: wire lifecycle events and tests
by rabsef-bicrym · 2026-02-03
73.7%
#19177: fix: use parseAgentSessionKey instead of fragile split pattern
by El-Patronum · 2026-02-17
72.5%
#18889: feat(hooks): add agent and tool lifecycle boundaries
by vincentkoc · 2026-02-17
72.4%
#19565: feat: add agent lifecycle hook events (session, message, error)
by tag-assistant · 2026-02-17
72.2%