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" }
  }
}
FieldTypeDescription
idstringUnique event id, prefix evt_. The same event keeps its id across retries and redeliveries, so use it to deduplicate.
objectstringAlways event.
typestringThe event type, for example run.waiting.
created_atstringWhen the event happened (ISO 8601, UTC). Not when it was delivered.
api_versionstringThe dated API revision used to render data.object.
workspace_idstringThe workspace the event belongs to, prefix ws_.
data.objectobjectA 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

HeaderExampleDescription
Content-Typeapplication/jsonAlways JSON, UTF-8.
X-Duun-Signaturet=1763203327,v1=5257a8…Timestamp and HMAC-SHA256 signature. See Verifying signatures.
X-Duun-Eventrun.waitingThe event type, so you can route before parsing the body.
X-Duun-Deliverywhd_4kP9sRUnique per delivery attempt. Redeliveries get a new id; the event id stays the same.
User-AgentDuun-Webhooks/1.0Identifies 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.failed and ask.created filtered to kind: "budget" or allow_command.
  • Mirroring the Inbox: ask.created and ask.resolved, matched on the ask id.
  • Release notes: pr.merged.
  • Spend monitoring: budget.threshold.

    Type to search the docs, help center and blog.