Skip to main content
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

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:

Manage webhooks

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. URLs must use HTTPS and resolve to a public address.

Verify signatures

Deliveries follow Standard Webhooks, 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_.
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"}.
  • MCP server: Tasks give MCP clients the same build progress
  • Files: uploads for endpoints that take documents