Webhook Contract

For chat traffic, the webhook is the cluster-internal contract between the orchestrator and a ZeroClaw runtime pod. Every user message routed to a swarm passes through this endpoint.

The orchestrator tells ZeroClaw which native agent slug to activate. ZeroClaw already knows that agent's provider, model, prompt, and skill directory from config.toml.

URL Format

POST http://{serviceName}.{namespace}.svc.cluster.local:42617/webhook

• serviceName — The ClusterIP Service name created for the UserSwarm
• namespace — The Kubernetes namespace where the runtime lives
• port 42617 — ZeroClaw's default HTTP port

This is a cluster-internal URL. ZeroClaw pods are not exposed through a public HTTPRoute; the orchestrator resolves the service over cluster DNS and proxies user traffic to it.

Request

Headers

Header	Value	Purpose
Content-Type	application/json	Standard JSON body
X-Session-Id	Conversation UUID	Links the request to a conversation for runtime session continuity

Body Fields

Field	Type	Required	Description
message	string	Yes	The user's message text
agent_id	string	No	Delegate-agent slug used to select a native ZeroClaw agent, for example wally
system_prompt	string	No	Optional override field in the transport contract, not part of the standard chat path

Example Request

{
  "message": "What meetings do I have tomorrow?",
  "agent_id": "wally"
}

Response

ZeroClaw returns a minimal JSON envelope:

{
  "response": "Based on your calendar, you have three meetings tomorrow..."
}

The orchestrator only reads the response field when decoding the webhook reply.

How Agent Routing Works

When the orchestrator routes a message to a specific workspace agent, it follows this flow:

1

Step 1

Choose a responder

The orchestrator decides whether the message should go to a specific delegate agent or to the base Manager path.

2

Step 2

Attach the agent slug

If a specific agent is selected, the orchestrator forwards only agent_id in the standard path.

3

Step 3

Send the webhook request

ZeroClaw receives the message and resolves agent_id against its native [agents.<slug>] configuration.

4

Step 4

Fall back to Manager

If no responder is selected, the orchestrator omits agent_id and the base Manager handles the turn.

The orchestrator chooses which agent should answer. ZeroClaw owns what that agent is through native config and per-agent skill files.

Session Continuity

The X-Session-Id header links requests to a conversation. The orchestrator forwards the conversation ID here so the runtime can maintain per-conversation state across turns.

Error Handling

If ZeroClaw encounters an error, it returns a non-200 HTTP status. The orchestrator includes the response body in its internal error handling and surfaces a generic API error back to the client.

What's Next

See Secrets Management to understand how API keys and credentials are delivered to ZeroClaw pods.