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

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# Webhooks

> Get signed events when a build or a call needs input, finishes or fails.

Peel sends an HTTPS `POST` to your webhook URL when a build or an execution job changes state, so you can wait for a long build or a call that pauses for a code without polling.

## Events

| Event | When | `data` |
| - | - | - |
| `build.needs_input` | A build asks a question | `build_id`, `api_id`, `question` (`key`, `prompt`, `secret`) |
| `build.completed` | A build published a version | `build_id`, `api_id`, `version_id` |
| `build.failed` | A build ended without publishing | `build_id`, `api_id`, `error_code` |
| `execution.needs_input` | An execution job asks for input | `execution_id`, `question` (`question_id`, `key`, `prompt`, `secret`), and `answer_url` for secrets |
| `execution.succeeded` | An execution job returned a result | `execution_id` |
| `execution.failed` | An execution job ended in any other state | `execution_id`, `state`, `error_code` |
| `api.repairing` | Automatic repair started rebuilding an API | `api_id`, `build_id` |
| `api.repaired` | A repair published a working version | `api_id`, `build_id`, `version_id` |
| `api.repair_failed` | A repair ended without a working version | `api_id`, `build_id`, `error_code` |
| `schedule.changed` | A [schedule](https://docs.peel.sh/features/schedules.md)'s answer changed | `schedule_id`, `api_id`, `endpoint_name`, `data` (or `data_omitted` above 64 KB) |
| `schedule.failed` | A scheduled run failed | `schedule_id`, `api_id`, `endpoint_name`, `error` |
| `webhook.test` | You called the test route | `webhook_id` |

Events never carry answers or secrets. Only `schedule.changed` carries result data, from an endpoint that needs no sign-in. Fetch the build with `GET /v1/apis/{api_id}` or the job with `GET /v1/executions/{execution_id}`. When a question is secret, send the user to `answer_url` so the code never passes through your system or a chat.

Every delivery is JSON:

```json theme={null}
{
  "id": "evt_3f6c0b8e2a7d4c51a9e04b7f1d2c6e88",
  "type": "build.completed",
  "created_at": "2026-11-04T07:04:00.000Z",
  "data": { "build_id": "…", "api_id": "…", "version_id": "…" }
}
```

## Manage webhooks

```bash theme={null}
curl https://api.peel.sh/v1/webhooks \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.org/hooks/peel", "events": ["build.completed", "build.failed"]}'
```

The response includes `secret` (`whsec_…`). It is shown only here and when you rotate it, so store it then. Leave out `events` to receive all of them.

| Route | Does |
| - | - |
| `GET /v1/webhooks` | Lists your webhooks without their secrets |
| `POST /v1/webhooks` | Creates one; up to 20 per account |
| `PATCH /v1/webhooks/{id}` | Changes `url`, `events` or `status` (`active`, `disabled`) |
| `DELETE /v1/webhooks/{id}` | Deletes one |
| `POST /v1/webhooks/{id}/test` | Sends a `webhook.test` event now and returns whether it was delivered |
| `POST /v1/webhooks/{id}/rotate-secret` | Replaces the signing secret and returns the new one |

URLs must use HTTPS and resolve to a public address.

## Verify signatures

Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com/), so its libraries verify them. Each request has three headers:

* `webhook-id`: the event `id`, the same on every retry. Use it to drop duplicates.
* `webhook-timestamp`: Unix seconds when this attempt was sent.
* `webhook-signature`: `v1,` followed by the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded part of your secret after `whsec_`.

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, headers: Headers, body: string): boolean {
  const id = headers.get("webhook-id") ?? "";
  const timestamp = Number(headers.get("webhook-timestamp"));
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = `v1,${createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64")}`;
  return (headers.get("webhook-signature") ?? "")
    .split(" ")
    .some((value) => value.length === expected.length && timingSafeEqual(Buffer.from(value), Buffer.from(expected)));
}
```

Verify against the raw request body, before parsing it.

## Delivery and retries

* Reply with any `2xx` within 10 seconds to acknowledge an event.
* Other replies and timeouts are retried after 5 seconds, 20 seconds, 1 minute, 3 minutes and 10 minutes.
* Pending events and their retries are stored, so they still arrive after Peel restarts. An event can arrive more than once; drop repeats by `webhook-id`.
* `410 Gone` turns the webhook off at once. `413` drops that event without retrying.
* Peel does not send to a domain whose owner opted out of Peel or that Peel blocks. That event is dropped without retrying and does not count as a failed event.
* A webhook whose last 20 events all failed is turned off. Turn it back on with `PATCH /v1/webhooks/{id}` and `{"status": "active"}`.

## Related pages

* [MCP server](https://docs.peel.sh/features/mcp-server.md): Tasks give MCP clients the same build progress
* [Files](https://docs.peel.sh/features/files.md): uploads for endpoints that take documents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.