Overview
Webhooks connect Rundun to your backend in real time. Every significant event in a checklist run fires a POST request to your configured endpoint. Your system can react immediately — trigger a notification, update a booking record, release a deposit — without polling the API.
Available events
| Event | Fires when | Default |
|---|---|---|
step.completed | A step is answered (all required photos taken) | On |
step.skipped | A non-required step is explicitly skipped | On |
run.completed | All required steps answered, run submitted | On |
run.cancelled | Executor exits before completing | On |
run.expired | Run link expires before completion | On |
Configuring webhooks
Webhook subscriptions are set per run at dispatch time:
POST /v1/runs
{
"template_id": "t-550e8400-...",
"webhook": {
"url": "https://your-app.com/hooks/rundun",
"secret": "whsec_your-secret-here",
"events": ["step.completed", "run.completed", "run.cancelled"]
},
"expires_in_hours": 24
}Only include events your backend needs to handle. Omitting step.completed reduces payload volume on long checklists.
Event payload
Every event uses the same envelope:
{
"event": "step.completed",
"event_id": "evt-7f3a9b12-...",
"delivery_attempt": 1,
"run_id": "r-550e8400-...",
"created_at": "2026-05-22T08:32:00Z",
"data": { ... }
}event_id is stable across retries — use it to deduplicate in your database. delivery_attempt increments from 1 to 5.
Retry schedule
If your endpoint doesn't return 2xx, Rundun retries with exponential backoff:
| Attempt | Delay after previous |
|---|---|
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |
| Final | 6 hours — then marked failed |
Best practices
Respond to webhooks immediately with HTTP 200 and process asynchronously. Slow responses risk timeouts and unnecessary retries. Store event_id in your database before processing to handle retries safely.
Always verify the signature before processing. See Signed delivery for the verification implementation.
Delivery infrastructure
Webhook delivery is handled by Rundun's dedicated delivery infrastructure — events are queued and delivered asynchronously, independently of the API. This ensures delivery even if your endpoint is temporarily unavailable, and that slow endpoints don't affect other users.