Webhooks

Webhooks send selected Polpo project events to your backend as signed HTTP POST requests.

Create a webhook

Dashboard
API

Open the project, then go to Project Settings > Webhooks and add an HTTPS endpoint.

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

The 201 response has this shape:

{
  "ok": true,
  "data": {
    "id": "9d4b3c54-5788-4adc-9dbe-f5ef9af2ad9c",
    "url": "https://example.com/polpo-webhook",
    "events": ["task:*", "mission:completed"],
    "created_at": "2026-07-13T10:05:00.000Z",
    "secret": "64-hex-character-signing-secret"
  }
}

The signing secret is returned only when the webhook is created or its secret is rotated. Store it before discarding the response.

If events is omitted, it defaults to ["*"].

Event filters

Filters support exact event names, category wildcards such as task:*, and the global * wildcard. Combine multiple filters in the events array. The event catalog is generated from the runtime and can change as event types are added. Read the current public catalog instead of maintaining a hard-coded list:

curl https://api.polpo.sh/v1/events/catalog

Payload

Every delivery body contains the event name, event-specific data, and an ISO timestamp:

{
  "event": "task:transition",
  "data": {
    "taskId": "task_123",
    "from": "in_progress",
    "to": "done"
  },
  "timestamp": "2026-07-13T10:05:00.000Z"
}

The delivery ID is not part of the JSON body. It is sent in a header.

Headers and signature

Each request includes:

Header	Value
`X-Polpo-Signature`	`t=<unix-seconds>,v1=<hex-hmac>`
`X-Polpo-Event`	Event name
`X-Polpo-Delivery-Id`	Delivery UUID
`User-Agent`	`Polpo-Webhook/1.0`

The signature is HMAC-SHA256 over <timestamp>.<raw-request-body>. Verify the raw bytes before parsing JSON and compare signatures in constant time:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyPolpoWebhook(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  const fields = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("=", 2)),
  );
  const timestamp = fields.t;
  const received = fields.v1;
  if (!timestamp || !received) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const expectedBytes = Buffer.from(expected, "hex");
  const receivedBytes = Buffer.from(received, "hex");
  return (
    expectedBytes.length === receivedBytes.length &&
    timingSafeEqual(expectedBytes, receivedBytes)
  );
}

Also reject timestamps outside a short tolerance window in your application to limit replay attacks.

Delivery and retries

A 2xx response marks an attempt successful. Each request has a 10-second timeout. Polpo retries network failures, timeouts, HTTP 408, HTTP 429, and 5xx responses. Backoff is exponential with jitter and is capped at one hour. A delivery is attempted at most five times. Other 4xx responses are treated as permanent failures. Every attempt is persisted with status, status code, truncated response body, error, duration, attempt number, and next retry time.

Delivery operations

List recent attempts, newest first:

curl "$POLPO_URL/v1/webhooks/{webhook-id}/deliveries?limit=50" \
  -H "Authorization: Bearer $POLPO_API_KEY"

Use the returned next_cursor as the before query parameter for the next page. Queue a new delivery from a past payload:

curl -X POST \
  "$POLPO_URL/v1/webhooks/{webhook-id}/deliveries/{delivery-id}/redeliver" \
  -H "Authorization: Bearer $POLPO_API_KEY"

Rotate the signing secret:

curl -X POST "$POLPO_URL/v1/webhooks/{webhook-id}/rotate-secret" \
  -H "Authorization: Bearer $POLPO_API_KEY"

Rotation returns the new secret once. New deliveries, including manual redeliveries, use the current secret.

Getting Started

Platform

Agents

Orchestration

Create a webhook

Event filters

Payload

Headers and signature

Delivery and retries

Delivery operations

​Create a webhook

​Event filters

​Payload

​Headers and signature

​Delivery and retries

​Delivery operations

Create a webhook

Event filters

Payload

Headers and signature

Delivery and retries

Delivery operations