Event catalog and payloads
Every webhook event Duun sends, when it fires, the event envelope, the request headers and a full example payload for each event type.
On this page
Duun sends ten event types to webhook endpoints. Each endpoint receives only the events you picked when you created it. You can change the list at any time with Edit events… in the endpoint menu, or with PATCH /webhook_endpoints/{endpoint_id}.
| Event | When it's sent | data.object |
|---|---|---|
| Runs | ||
run.started | A run begins. | run |
run.waiting | A run needs a human: a new ask is open. | run |
run.failed | A run failed after retries. | run |
run.succeeded | A run finished green. | run |
| Asks | ||
ask.created | A new ask lands in someone's inbox. | ask |
ask.resolved | An ask was approved, answered or declined. | ask |
| Pull requests | ||
pr.opened | An agent opened a pull request. | pull_request |
pr.merged | A pull request from a run was merged. | pull_request |
| Workspace | ||
budget.threshold | Spend passed one of a budget's alert thresholds. | budget_alert |
machine.created | A new sandbox or computer was created. | machine |
The event envelope
Every delivery is a POST with a JSON body in the same envelope. The resource the event is about sits in data.object, in the same shape the API returns.
{
"id": "evt_9xYb20Kd",
"object": "event",
"type": "run.waiting",
"created_at": "2026-11-15T10:42:07Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": { "id": "run_7f3aK2pQ", "object": "run" }
}
}| Field | Type | Description |
|---|---|---|
id | string | Unique event id, prefix evt_. The same event keeps its id across retries and redeliveries, so use it to deduplicate. |
object | string | Always event. |
type | string | The event type, for example run.waiting. |
created_at | string | When the event happened (ISO 8601, UTC). Not when it was delivered. |
api_version | string | The dated API revision used to render data.object. |
workspace_id | string | The workspace the event belongs to, prefix ws_. |
data.object | object | A snapshot of the resource at the time of the event: a run, ask, pull request, budget alert or machine. |
Payloads are snapshots. If you need the current state, fetch the resource with the API, for example GET /runs/{run_id}.
Request headers
| Header | Example | Description |
|---|---|---|
Content-Type | application/json | Always JSON, UTF-8. |
X-Duun-Signature | t=1763203327,v1=5257a8… | Timestamp and HMAC-SHA256 signature. See Verifying signatures. |
X-Duun-Event | run.waiting | The event type, so you can route before parsing the body. |
X-Duun-Delivery | whd_4kP9sR | Unique per delivery attempt. Redeliveries get a new id; the event id stays the same. |
User-Agent | Duun-Webhooks/1.0 | Identifies Duun’s sender. |
Run events
Run events carry the full run object in data.object.
run.started
Fires when a run leaves the queue and its first step begins. Queued runs that are waiting on a concurrency limit or a budget don’t fire run.started until they actually start.
{
"id": "evt_9xYa01Fm",
"object": "event",
"type": "run.started",
"created_at": "2026-11-15T10:38:12Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "running",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": "plan",
"branch": "duun/plt-482-idempotency-keys",
"ask": null,
"pull_request": null,
"cost": { "spent_usd": 0.0, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"created_at": "2026-11-15T10:38:09Z",
"updated_at": "2026-11-15T10:38:12Z",
"finished_at": null
}
}
}run.waiting
Fires when a run stops and needs a person: a plan to approve, a command to allow, questions to answer, a pull request to review, or a budget decision. The run’s ask field says which. An ask.created event fires at the same moment if you subscribe to it.
{
"id": "evt_9xYb20Kd",
"object": "event",
"type": "run.waiting",
"created_at": "2026-11-15T10:42:07Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "waiting",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": "plan",
"branch": "duun/plt-482-idempotency-keys",
"ask": {
"id": "ask_3h2Wn8",
"kind": "approve_plan",
"title": "Approve the plan",
"created_at": "2026-11-15T10:42:07Z"
},
"pull_request": null,
"cost": { "spent_usd": 1.84, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"created_at": "2026-11-15T10:38:09Z",
"updated_at": "2026-11-15T10:42:07Z",
"finished_at": null
}
}
}run.failed
Fires when a run ends in failed: a step failed and its retries and failure policy were used up, the run hit its timeout, or a gate returned to an earlier step more than its maximum attempts. The run’s current_step is the step that failed.
{
"id": "evt_9xYc77Qa",
"object": "event",
"type": "run.failed",
"created_at": "2026-11-15T11:20:41Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"id": "run_4Rm8dTq1",
"object": "run",
"title": "Backfill payout currency on legacy rows",
"status": "failed",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-463", "url": "https://linear.app/acme/issue/PLT-463" },
"agent": "operator",
"current_step": "migrate-staging",
"branch": "duun/plt-463-backfill-payout-currency",
"ask": null,
"pull_request": null,
"cost": { "spent_usd": 0.9, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"created_at": "2026-11-15T10:50:02Z",
"updated_at": "2026-11-15T11:20:41Z",
"finished_at": "2026-11-15T11:20:41Z"
}
}
}run.succeeded
Fires when a run finishes green: every step on its route succeeded. For workflows that end in a Deliver step with Merge on green, this usually follows pr.merged.
{
"id": "evt_9xYd31Lp",
"object": "event",
"type": "run.succeeded",
"created_at": "2026-11-15T12:09:55Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "succeeded",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": "deliver",
"branch": "duun/plt-482-idempotency-keys",
"ask": null,
"pull_request": { "number": 1288, "url": "https://github.com/acme/platform/pull/1288", "state": "merged" },
"cost": { "spent_usd": 4.62, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"created_at": "2026-11-15T10:38:09Z",
"updated_at": "2026-11-15T12:09:55Z",
"finished_at": "2026-11-15T12:09:55Z"
}
}
}Ask events
Ask events carry an ask object. Use them to mirror Duun’s Inbox in another tool, for example a Slack bot that posts every new ask to an on-call channel.
ask.created
Fires when a new ask lands in someone’s Inbox. kind is one of approve_plan, allow_command, answer, review_pr or budget.
{
"id": "evt_9xYb20Ke",
"object": "event",
"type": "ask.created",
"created_at": "2026-11-15T10:42:07Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "ask",
"id": "ask_3h2Wn8",
"run_id": "run_7f3aK2pQ",
"kind": "approve_plan",
"title": "Approve the plan",
"status": "open",
"resolution": null
}
}
}ask.resolved
Fires when an ask is approved, answered or declined, whether in the app, from Slack, by an auto-approve countdown or through POST /runs/{run_id}/asks/{ask_id}/resolve. resolution.by is a member’s name, or auto for countdowns.
{
"id": "evt_9xYb5mTz",
"object": "event",
"type": "ask.resolved",
"created_at": "2026-11-15T10:49:30Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "ask",
"id": "ask_3h2Wn8",
"run_id": "run_7f3aK2pQ",
"kind": "approve_plan",
"title": "Approve the plan",
"status": "resolved",
"resolution": { "action": "approve", "by": "Dana Kim", "at": "2026-11-15T10:49:30Z" }
}
}
}Pull request events
pr.opened
Fires when an agent opens a pull request from a run’s branch, usually in a Deliver step. Draft pull requests count.
{
"id": "evt_9xYcA2Hn",
"object": "event",
"type": "pr.opened",
"created_at": "2026-11-15T11:31:18Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "pull_request",
"run_id": "run_7f3aK2pQ",
"repo": "acme/platform",
"number": 1288,
"url": "https://github.com/acme/platform/pull/1288",
"title": "Idempotency keys for refund webhooks",
"state": "open",
"merged_by": null
}
}
}pr.merged
Fires when a pull request opened by a run is merged, by a person or by Merge on green. merged_by is a member’s name, or duun when Duun merged it.
{
"id": "evt_9xYd2vBc",
"object": "event",
"type": "pr.merged",
"created_at": "2026-11-15T12:09:41Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "pull_request",
"run_id": "run_7f3aK2pQ",
"repo": "acme/platform",
"number": 1288,
"url": "https://github.com/acme/platform/pull/1288",
"title": "Idempotency keys for refund webhooks",
"state": "merged",
"merged_by": "duun"
}
}
}Workspace events
budget.threshold
Fires when spend in a budget’s scope passes one of its alert thresholds (for example 50, 80 or 100 percent). One event fires per threshold per period. scope.kind is one of workspace, project, factory, workflow, member or agent. See Usage and budgets.
{
"id": "evt_9xYe8sWq",
"object": "event",
"type": "budget.threshold",
"created_at": "2026-11-15T15:02:10Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "budget_alert",
"budget_id": "bud_8Tn3",
"scope": { "kind": "factory", "id": "fac_platform" },
"pct": 80,
"spent_usd": 96.4,
"limit_usd": 120.0
}
}
}machine.created
Fires when a cloud sandbox, desktop or SSH computer is added to the workspace, including sandboxes a run starts on its own. run_id is null for machines created by hand.
{
"id": "evt_9xYf0kRn",
"object": "event",
"type": "machine.created",
"created_at": "2026-11-15T10:38:10Z",
"api_version": "2026-11-01",
"workspace_id": "ws_acme",
"data": {
"object": {
"object": "machine",
"id": "sbx-7f3a",
"kind": "sandbox",
"size": "large",
"region": "eu-west-1",
"run_id": "run_7f3aK2pQ"
}
}
}Choosing events
- Status page or dashboard:
run.started,run.succeeded,run.failed. - On-call bridge:
run.failedandask.createdfiltered tokind: "budget"orallow_command. - Mirroring the Inbox:
ask.createdandask.resolved, matched on the askid. - Release notes:
pr.merged. - Spend monitoring:
budget.threshold.