Polymath Zero

Developers

Webhooks

Zero delivers webhook payloads to registered URLs when Work items change, sessions complete, or proof is created. All events originate from the local Zero runtime. Webhooks are available in current releases.

Provider transport boundary. In current builds, Zero uses local CLI transport for session execution. Session events (session_started, session_completed, agent_completed) fire as the local CLI runner executes. The provider field in event payloads reflects the configured local CLI runner. When API-based provider transport ships, session events will fire identically — only the transport path changes.
What ships now. All Work item state events, session events, and proof events are available in current releases. Signature verification is available. Provider transport for session execution uses local CLI in current builds — API-based transport is planned and will fire identical events.

Events

Sessions begin in Plan mode (agent proposes) and transition to Work mode after the operator approves the plan. The session_started event fires when a session begins executing in Work mode.agent_completed fires at the end of either Plan mode or Work mode.

Primary execution events:

event_typeTrigger
session_startedSession begins executing. Payload includes case_id, session_id, provider.
session_completedSession execution finishes and output is written. Payload includes case_id, session_id.
proof_createdProof artifact attached to a Work item. Payload includes case_id, proof_id, proof_type.
proof_updatedProof artifact updated or verified.
agent_completedAgent run finishes (plan or work mode).

Work item state events:

event_typeTrigger
case_updatedWork item fields updated. Payload includes case_id.
case_state_changedWork item execution state changes. Payload includes case_id, old_state, new_state. The PLANNING→IMPLEMENTING transition fires when the operator approves the plan (Work mode begins).

Payload format

All webhook payloads are JSON with a top-level event_type, timestamp, and payload wrapper:

{
  "event_type": "session_completed",
  "timestamp": "2026-04-27T10:00:00Z",
  "payload": {
    "case_id": "uuid-v4",
    "session_id": "uuid-v4"
  }
}

case_state_changed is a compatibility event that mirrors internal execution state. For most integrations, prefer session_completed and proof_created — they describe work done, not internal transitions. case_state_changed is useful for external systems (dashboards, Jira sync) that need to track execution status:

{
  "event_type": "case_state_changed",
  "timestamp": "2026-04-27T10:00:00Z",
  "payload": {
    "case_id": "uuid-v4",
    "old_state": "IMPLEMENTING",
    "new_state": "VERIFYING"
  }
}

Signature verification

Every delivery includes an X-Zero-Signature header and an X-Zero-Event header. Verify X-Zero-Signature against your webhook secret to confirm the payload is from Zero.

X-Zero-Event: session_completed
X-Zero-Signature: sha256=<hmac-hex>

Registration

Global webhooks — receive events for all Work items in the workspace:

# Register
POST /webhooks
Content-Type: application/json

{
  "url": "https://your-server.example.com/zero-events",
  "events": ["session_completed", "proof_created"],
  "secret": "your-secret"
}

# List
GET /webhooks

# Delete
DELETE /webhooks/:id

Case-scoped webhooks — receive events for a specific Work item:

# Register
POST /cases/:id/webhooks
Content-Type: application/json

{ "url": "https://your-server.example.com/zero-events" }

# List
GET /cases/:id/webhooks

# Delete
DELETE /cases/:id/webhooks/:webhook_id
Set "events": ["*"] on a global webhook to receive all event types.

SSE streaming

For real-time session execution output, use SSE streaming instead of webhooks. SSE delivers events as they happen during an active session:

curl -N http://localhost:7878/cases/:id/sessions/:sid/stream

Webhooks are better for external integrations. SSE is better for live UI or terminal tailing of a running session.