Webhooks
Webhooks overview
Subscribe to PromptFloe events and receive HMAC-signed POSTs at your endpoint. Use webhooks instead of streaming when the work is long-running, when you need durable delivery, or when the consumer is a different process from the caller.
#When to use webhooks
- Async deploy notifications — triggered builds can take 30–60s; let the call return and react to the completion event.
- Multi-tenant fan-out — your platform kicks off many runs; receive results in one place.
- Cross-process consumers — the build is triggered from a CLI but a worker handles results.
#Subscribe to events
1
Register your endpoint
await client.webhooks.create({
url: 'https://yourapp.com/webhooks/promptfloe',
events: [
'app.generated',
'deployment.live',
'deployment.failed',
'skill.completed',
],
});2
Capture the signing secret
The response includes a secret field — capture it. We show it once and never again. Use it to verify HMAC signatures on incoming deliveries (see Verification).
3
Receive deliveries
POST /webhooks/promptfloe
Content-Type: application/json
X-PromptFloe-Signature: t=1730000000,v1=...
X-PromptFloe-Event: app.generated
X-PromptFloe-Delivery: deliv_xxx
{
"id": "evt_xxx",
"type": "app.generated",
"createdAt": "2026-04-26T12:34:56Z",
"data": {
"appId": "app_abc",
"previewUrl": "https://..."
}
}#Delivery semantics
- At-least-once delivery — your handler must be idempotent. Use
X-PromptFloe-Deliveryas the dedupe key. - Retry policy — exponential backoff at 1m, 5m, 30m, 2h, 12h, 24h. After 6 failed attempts the delivery is marked as failed and the endpoint enters a degraded state.
- Acknowledge with 2xx — any response in 200–299 is treated as success. Anything else is a retry.
- Timeout — we wait 10 seconds for your response. Slow handlers should ack quickly and process asynchronously.
#Manage subscriptions
bash
# List
GET /v1/webhooks
# Get one
GET /v1/webhooks/:id
# Update (events, url, enabled)
PATCH /v1/webhooks/:id
# Delete
DELETE /v1/webhooks/:id
# Replay a delivery
POST /v1/webhooks/:id/deliveries/:deliveryId/replay#Where to go next
PromptFloe developer docs