#10663: feat(hooks): add agentId support for webhook routing
gateway
stale
## Summary
Adds `agentId` field to hook mappings, allowing webhooks to route to specific agents instead of always using the default agent.
## Motivation
This enables multi-agent architectures where different webhook endpoints can target different agent instances. For example, a project management system can route notifications to project-specific agents.
## Changes
- Add `agentId` to `HookMappingConfig` type and zod schema
- Add `agentId` to `HookMappingResolved` and `HookAction` types
- Thread `agentId` through `normalizeAgentPayload` and `dispatchAgentHook`
- Pass `agentId` to `runCronIsolatedAgentTurn` (which already supported it)
## Usage
### Static routing in config:
```yaml
hooks:
mappings:
- id: project-a
match: { path: "project-a" }
action: agent
agentId: agent-a
messageTemplate: "{{message}}"
```
### Dynamic routing from payload:
```yaml
hooks:
mappings:
- id: dynamic
match: { path: "webhook" }
action: agent
agentId: "{{targetAgent}}"
messageTemplate: "{{message}}"
```
### Direct /hooks/agent endpoint:
```json
{
"message": "Hello",
"agentId": "my-agent"
}
```
## Testing
- Built and tested locally
- Verified webhook routing to different agents works correctly
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
- Extends hook mapping/config types and schema to support an optional `agentId`.
- Threads `agentId` through mapping normalization/templating so it can be statically configured or dynamically rendered from the webhook payload.
- Passes `agentId` through the HTTP hook handlers so `/hooks/*` requests can route to a non-default agent.
- Updates the cron-isolated agent turn dispatch path to accept the requested `agentId`.
<h3>Confidence Score: 3/5</h3>
- This PR is close, but has a concrete hook-dispatch typing/threading issue that can prevent `agentId` from being forwarded correctly.
- Changes are mostly additive and consistently threaded through config/mapping, but `dispatchAgentHook`'s declared parameter shape in `server-http.ts` omits `agentId` while call sites now pass it, which indicates a real integration gap (and may fail type-check or drop the value depending on implementation).
- src/gateway/server-http.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
#9800: feat(hooks): allow webhook mappings to route to specific agents via a…
by bogdanClawdy · 2026-02-05
93.8%
#10383: feat(hooks): add agentId to hook mappings
by quentintou · 2026-02-06
93.8%
#7846: feat: add agentId param to webhook agent endpoint
by Bre77 · 2026-02-03
87.7%
#7301: fix(hooks): use resolveAgentIdFromSessionKey instead of split(":")[0]
by tsukhani · 2026-02-02
80.3%
#6630: feat(hooks): add agent:turn_start and agent:turn_end lifecycle events
by drdigital13 · 2026-02-01
76.9%
#19565: feat: add agent lifecycle hook events (session, message, error)
by tag-assistant · 2026-02-17
75.1%
#7771: Hooks: wire lifecycle events and tests
by rabsef-bicrym · 2026-02-03
74.8%
#11597: feat(hooks): implement message:received hook
by gnufoo · 2026-02-08
73.3%
#18712: feat(hooks): add responseUrl callback with security hardening
by shanefirek · 2026-02-17
73.3%
#12635: Gateway: add inbound webhook dispatch framework
by jhs129 · 2026-02-09
73.1%