Polymath Zero

Developers

Webhooks

Zero delivers webhook payloads to registered URLs when Work items change, sessions complete, or proof is created. Webhooks are available now.

Events

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.

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 example:

{
  "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.