openclaw - 💡(How to fix) Fix Feature Request: agentId support in webhook hook mappings [1 participants]

Problem

In a multi-agent setup, webhook hook mappings always dispatch to the default agent regardless of the webhook path or payload. There's no way to route a webhook to a specific agent.

The runCronIsolatedAgentTurn function already supports params.agentId and params.job.agentId, but the hook dispatch path in gateway/server/hooks.js never sets agentId on the job object. The normalizeHookMapping function in hooks-mapping.js also doesn't extract or pass through an agentId field.

Confirmed missing in both 2026.1.24-3 and 2026.3.8.

Use Case

We run 5 agents on one instance (frontend, backend, marketer, designer, research). An external orchestrator API creates tasks and assigns them to specific agents. We want to notify the right agent immediately via webhook rather than waiting for heartbeat polling.

Current workaround: each agent polls the orchestrator API on heartbeat (every 10m). This works but adds latency. The webhook system is the right mechanism — it just needs agent targeting.

Proposed Solution

Add an agentId field to hook mappings, threaded through to the job:

In hooks-mapping.js → normalizeHookMapping:

return {
    id,
    matchPath,
    // ... existing fields ...
    agentId: mapping.agentId,  // NEW
};

In gateway/server/hooks.js → dispatchAgentHook:

const job = {
    // ... existing fields ...
    agentId: value.agentId,  // NEW — picked up by runCronIsolatedAgentTurn
};

In hooks-mapping.js → buildActionFromMapping:

return {
    ok: true,
    action: {
        kind: agent,
        // ... existing fields ...
        agentId: renderOptional(mapping.agentId, ctx),  // NEW
    },
};

Config usage:

{
  hooks: {
    mappings: [
      {
        id: task-frontend,
        match: { path: frontend },
        action: agent,
        agentId: frontend,
        messageTemplate: 🎯 New task: {{title}}n{{message}}
      },
      {
        id: task-backend,
        match: { path: backend },
        action: agent,
        agentId: backend,
        messageTemplate: 🎯 New task: {{title}}n{{message}}
      }
    ]
  }
}

This would also support template rendering (agentId: {{workspace}}) for dynamic routing from the payload.

Alternatives Considered

• Heartbeat polling: Works but adds up to N minutes of latency (N = heartbeat interval)
• Transform modules: Could intercept and modify the action, but transforms can't set agentId since it's not part of the action schema
• Separate gateway instances per agent: Excessive overhead for what should be a config field

Environment

• Confirmed missing in OpenClaw 2026.3.8 (latest) and 2026.1.24-3
• Multi-agent setup with 5 agents on one instance