Skip to main content
Webhooks deliver HTTP POST requests to your server whenever events happen in a Polpo project — task transitions, mission completions, agent activity, and more.

​
How it works

  1. Register a webhook URL and choose which events to receive
  2. When a matching event fires, Polpo sends a POST request to your URL
  3. Your server processes the payload and responds with a 2xx status

​
Setting up webhooks

Go to Project Settings > Webhooks and click Add webhook. Enter your endpoint URL and select which events to subscribe to.

​
Event patterns

Use wildcards to subscribe to groups of events:
PatternWhat you receive
*Everything
task:*Task created, assigned, transitioned, completed, failed, killed
mission:*Mission executed, completed, aborted
agent:*Agent spawned, output, completed
assessment:*Assessment started, scored, completed
approval:*Approval requested, resolved, timed out
schedule:*Schedule triggered, created, completed
You can combine multiple patterns: ["task:transition", "mission:completed"].

​
Payload format

Every webhook delivery contains: 
{
  "id": "evt_xyz789",
  "event": "task:transition",
  "timestamp": "2026-03-20T10:05:00Z",
  "data": {
    "taskId": "task_123",
    "from": "in_progress",
    "to": "done",
    "task": { ... }
  }
}
The data field varies by event type. See Events API for the full list of event types and their payloads.

​
Webhooks vs SSE

WebhooksSSE
DirectionServer → your serverServer → browser
Use caseBackend integrationsReal-time dashboards
DeliveryBest-effort, no retryResumable with Last-Event-ID
SetupRegister URLOpen EventSource connection
You can use both simultaneously.

​
Event payloads

The data field varies by event type. Webhook payloads use the same structures as the SSE events — see the full catalog with all payloads in the Events reference. Task and mission objects in payloads follow the same schemas documented in Tasks reference and Missions reference.

​
Delivery

  • Deliveries are at most once (fire-and-forget)
  • Failed deliveries are not retried
  • Events are delivered in emission order