Skip to main content
Webhooks let you subscribe to events happening in your project. When an event fires, Polpo sends an HTTP POST request to your configured endpoint with the event payload.

​
Endpoints

MethodPathDescription
GET/v1/webhooksList all webhooks
POST/v1/webhooksCreate a webhook
DELETE/v1/webhooks/{id}Delete a webhook

​
Create a webhook

curl -X POST https://api.polpo.sh/v1/webhooks \
  -H "x-api-key: $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["task:*", "mission:completed"]
  }'

​
Request body

​
url
string
required
The HTTPS endpoint that will receive POST requests.
​
events
string[]
required
Event patterns to subscribe to. Supports wildcards.Examples:
  • ["*"] — all events
  • ["task:*"] — all task events
  • ["task:created", "task:transition"] — specific events
  • ["mission:*", "agent:*"] — multiple patterns

​
Response

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://example.com/webhook",
    "events": ["task:*", "mission:completed"],
    "created_at": "2026-03-20T10:00:00Z"
  }
}

​
List webhooks

curl https://api.polpo.sh/v1/webhooks \
  -H "x-api-key: $POLPO_API_KEY"

​
Response

{
  "ok": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://example.com/webhook",
      "events": ["task:*", "mission:completed"],
      "created_at": "2026-03-20T10:00:00Z"
    }
  ]
}

​
Delete a webhook

curl -X DELETE https://api.polpo.sh/v1/webhooks/wh_abc123 \
  -H "x-api-key: $POLPO_API_KEY"

​
Event payload

When an event matches your subscription, Polpo sends a POST request to your URL with this payload: 
{
  "id": "evt_xyz789",
  "event": "task:transition",
  "timestamp": "2026-03-20T10:05:00Z",
  "data": {
    "taskId": "task_123",
    "from": "in_progress",
    "to": "done",
    "task": { ... }
  }
}
The event field matches the same event names used in SSE events.

​
Available event patterns

PatternDescription
*All events
task:*Task created, transition, updated, retry, killed
mission:*Mission executed, completed, aborted, saved
agent:*Agent spawned, output, completed
assessment:*Assessment started, completed, score
approval:*Approval requested, resolved, timeout
schedule:*Schedule triggered, created, completed

​
Delivery behavior

  • Webhooks are delivered at most once (fire-and-forget)
  • Failed deliveries are not retried
  • Delivery order follows event emission order
  • Maximum 10 webhooks per project
  • Endpoint must respond within 10 seconds
Webhook delivery is best-effort. For guaranteed delivery, use SSE events with Last-Event-ID replay.

​
SDK usage

import { PolpoClient } from "@polpo-ai/sdk";

const client = new PolpoClient({
  baseUrl: "https://api.polpo.sh",
  apiKey: "pk_live_...",
});

// Create
await client.createWebhook({
  url: "https://example.com/webhook",
  events: ["task:*"],
});

// List
const webhooks = await client.getWebhooks();

// Delete
await client.deleteWebhook("wh_abc123");