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
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 eventid, 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 afterwhsec_.
Delivery and retries
- Reply with any
2xxwithin 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 Goneturns the webhook off at once.413drops 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: Tasks give MCP clients the same build progress
- Files: uploads for endpoints that take documents