> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive signed HTTP notifications for project events

## Endpoints

| Method   | Path                                                  | Description               |
| -------- | ----------------------------------------------------- | ------------------------- |
| `GET`    | `/v1/webhooks`                                        | List webhooks             |
| `POST`   | `/v1/webhooks`                                        | Create a webhook          |
| `PATCH`  | `/v1/webhooks/{id}`                                   | Update a webhook          |
| `DELETE` | `/v1/webhooks/{id}`                                   | Delete a webhook          |
| `GET`    | `/v1/webhooks/{id}/deliveries`                        | List deliveries           |
| `POST`   | `/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver` | Redeliver an event        |
| `POST`   | `/v1/webhooks/{id}/rotate-secret`                     | Rotate the signing secret |

## Create

```bash theme={null}
curl -X POST https://{project}.polpo.cloud/v1/webhooks \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/polpo","events":["task:*"]}'
```

`events` is optional and defaults to `["*"]`. Event patterns support `*`, category wildcards such as `task:*`, and exact names. Query the public `GET https://api.polpo.sh/v1/events/catalog` endpoint for the webhook event catalog.

The create response is `201 Created`. Its `secret` is shown only once:

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/polpo",
    "events": ["task:*"],
    "secret": "7f42b5..."
  }
}
```

## Event payload and signature

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

Every delivery includes:

```http theme={null}
X-Polpo-Signature: t=1783937100,v1=<hex-hmac>
X-Polpo-Event: task:transition
X-Polpo-Delivery-Id: <uuid>
```

Compute HMAC-SHA256 over `<timestamp>.<raw request body>` with the secret and compare its hex digest to `v1` using a timing-safe comparison. Reject stale timestamps. Store the one-time secret or rotate it with the rotate endpoint.

## Delivery behavior

Polpo considers any `2xx` response successful and waits up to 10 seconds. Network errors, `408`, `429`, and `5xx` responses are retried with exponential backoff and jitter, for up to five attempts; other `4xx` responses are permanent failures. Delivery history can be paginated with `limit` and `before`, and a delivery can be redelivered manually.

<Note>If your SDK version does not expose webhook helpers, manage webhooks through these HTTP endpoints.</Note>