Webhook endpoints

Manage outgoing webhook endpoints, their signing secrets and delivery log, and incoming trigger URLs that start runs, through the Duun API.

On this page

Webhooks go both ways. Endpoints are your URLs that Duun calls when something happens: a run starts, needs a human, fails or succeeds, an ask is created or resolved, a pull request opens or merges, spend passes a threshold, or a machine is created. Trigger URLs are Duun URLs your systems call to start a run.

This page covers managing both through the API. For the event payloads, signature verification and retry schedule, see Webhooks, Event catalog and Verifying signatures.

The webhook endpoint object

FieldTypeDescription
idstringUnique id, prefixed whe_.
objectstringAlways "webhook_endpoint".
urlstringYour public https:// URL.
eventsstring[]Event types it receives, e.g. run.waiting.
descriptionstring | nullHelps teammates know what it feeds.
statusenumactive, paused (no events are sent) or failing (every delivery has failed for 24 hours; Duun keeps trying new events).
secretstringThe signing secret, prefixed whsec_. Only returned when the endpoint is created or its secret is rotated. Otherwise null.
created_atstringWhen it was created.
Webhook endpoint
{
  "id": "whe_4kQ9mT",
  "object": "webhook_endpoint",
  "url": "https://hooks.acme.dev/duun",
  "events": ["run.waiting", "run.failed", "pr.merged"],
  "description": "On-call bridge",
  "status": "active",
  "secret": null,
  "created_at": "2026-10-11T08:30:00Z"
}

Events

EventWhen it fires
run.startedA run begins
run.waitingA run needs a human
run.failedA run failed after retries
run.succeededA run finished green
ask.createdA new ask lands in someone’s inbox
ask.resolvedAn ask was approved, answered or declined
pr.openedAn agent opened a pull request
pr.mergedA pull request was merged
budget.thresholdSpend passed a budget threshold
machine.createdA new sandbox or computer was created

The delivery object

FieldTypeDescription
idstringUnique id, prefixed whd_. Sent as the X-Duun-Delivery header.
objectstringAlways "webhook_delivery".
endpoint_idstringThe endpoint it was sent to.
event_idstringThe event, prefixed evt_. Redeliveries of the same event share it.
event_typestringE.g. run.waiting.
statusenumsucceeded, retrying or failed.
attemptsintegerAttempts so far.
response_codeinteger | nullYour server’s last status code. null for timeouts and connection errors.
duration_msinteger | nullHow long your server took on the last attempt.
next_attempt_atstring | nullWhen the next retry is scheduled, while retrying.
created_atstringWhen the first attempt was made.

Deliveries are kept for 7 days.

Endpoints

List webhook endpoints

GET https://api.duun.ai/v1/webhook_endpoints

Returns the workspace’s outgoing endpoints. Needs webhooks:read.

Query parameters

status enum Optional

Only endpoints in this status.

One of active paused failing

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from the previous page.

curl https://api.duun.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer $DUUN_API_KEY"
import Duun from "@duun/sdk";

const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });

for await (const endpoint of duun.webhookEndpoints.list()) {
  console.log(endpoint.url, endpoint.status, endpoint.events.join(", "));
}
from duun import Duun

client = Duun()

for endpoint in client.webhook_endpoints.list():
    print(endpoint.url, endpoint.status, ", ".join(endpoint.events))
Response
{
  "object": "list",
  "data": [
    {
      "id": "whe_4kQ9mT",
      "object": "webhook_endpoint",
      "url": "https://hooks.acme.dev/duun",
      "events": ["run.waiting", "run.failed", "pr.merged"],
      "description": "On-call bridge",
      "status": "active",
      "secret": null,
      "created_at": "2026-10-11T08:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a webhook endpoint

POST https://api.duun.ai/v1/webhook_endpoints

Adds an endpoint. The response includes the signing secret; it’s shown once, so store it in your secret manager now. Needs webhooks:write.

Body parameters

url string Required

A public https:// URL, e.g. https://hooks.acme.dev/duun. Private and loopback addresses are refused.

events string[] Required

At least one event type from the list above.

description string Optional

Helps teammates know what it feeds.

curl https://api.duun.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://hooks.acme.dev/duun",
    "events": ["run.waiting", "run.failed", "pr.merged"],
    "description": "On-call bridge"
  }'
const endpoint = await duun.webhookEndpoints.create({
  url: "https://hooks.acme.dev/duun",
  events: ["run.waiting", "run.failed", "pr.merged"],
  description: "On-call bridge",
});
// Store endpoint.secret now: it is only returned here.
endpoint = client.webhook_endpoints.create(
    url="https://hooks.acme.dev/duun",
    events=["run.waiting", "run.failed", "pr.merged"],
    description="On-call bridge",
)
# Store endpoint.secret now: it is only returned here.
Response
{
  "id": "whe_4kQ9mT",
  "object": "webhook_endpoint",
  "url": "https://hooks.acme.dev/duun",
  "events": ["run.waiting", "run.failed", "pr.merged"],
  "description": "On-call bridge",
  "status": "active",
  "secret": "whsec_7hd2kq9xm4tpb3nzr8vc6wjyfa5se2",
  "created_at": "2026-11-15T12:00:00Z"
}

Errors worth handling:

  • 400 invalid_request with param: "url" for non-https, private or loopback URLs.
  • 400 invalid_request with param: "events" for an empty list or an unknown event type.

Retrieve a webhook endpoint

GET https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}

Returns one endpoint, without its secret. Needs webhooks:read.

Path parameters

endpoint_id string Required

The endpoint's id, e.g. whe_4kQ9mT.

curl https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT \
  -H "Authorization: Bearer $DUUN_API_KEY"
const endpoint = await duun.webhookEndpoints.retrieve("whe_4kQ9mT");
endpoint = client.webhook_endpoints.retrieve("whe_4kQ9mT")

The response is a webhook endpoint object.

Update a webhook endpoint

PATCH https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}

Changes the URL, events or description, or pauses and resumes the endpoint. A paused endpoint gets no events; events that happen while it’s paused aren’t queued. Needs webhooks:write.

Path parameters

endpoint_id string Required

The endpoint's id.

Body parameters

url string Optional

A new public https:// URL.

events string[] Optional

Replaces the list. At least one.

description string Optional

Helps teammates know what it feeds.

status enum Optional

Pause or resume. failing is set by Duun and can't be sent.

One of active paused

curl -X PATCH https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["run.waiting", "run.failed", "pr.merged", "budget.threshold"] }'
await duun.webhookEndpoints.update("whe_4kQ9mT", {
  events: ["run.waiting", "run.failed", "pr.merged", "budget.threshold"],
});
client.webhook_endpoints.update(
    "whe_4kQ9mT",
    events=["run.waiting", "run.failed", "pr.merged", "budget.threshold"],
)
Response
{
  "id": "whe_4kQ9mT",
  "object": "webhook_endpoint",
  "url": "https://hooks.acme.dev/duun",
  "events": ["run.waiting", "run.failed", "pr.merged", "budget.threshold"],
  "description": "On-call bridge",
  "status": "active",
  "secret": null,
  "created_at": "2026-10-11T08:30:00Z"
}

Delete a webhook endpoint

DELETE https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}

The endpoint stops receiving events immediately. Queued retries are dropped. Needs webhooks:write.

Path parameters

endpoint_id string Required

The endpoint's id.

curl -X DELETE https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT \
  -H "Authorization: Bearer $DUUN_API_KEY"
await duun.webhookEndpoints.delete("whe_4kQ9mT");
client.webhook_endpoints.delete("whe_4kQ9mT")
Response
{ "id": "whe_4kQ9mT", "object": "webhook_endpoint", "deleted": true }

Rotate the signing secret

POST https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}/rotate_secret

Issues a new signing secret, returned once. With a grace window, deliveries carry two v1= signatures (old and new secret) until the window ends, so you can deploy the new secret without dropping events. Needs webhooks:write.

Path parameters

endpoint_id string Required

The endpoint's id.

Body parameters

expire_after enum Optional

How long the old secret keeps signing deliveries. now stops using it at once.

Default now

One of now 1h 24h

curl https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT/rotate_secret \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "expire_after": "24h" }'
const { secret } = await duun.webhookEndpoints.rotateSecret("whe_4kQ9mT", { expire_after: "24h" });
endpoint = client.webhook_endpoints.rotate_secret("whe_4kQ9mT", expire_after="24h")
new_secret = endpoint.secret
Response
{
  "id": "whe_4kQ9mT",
  "object": "webhook_endpoint",
  "url": "https://hooks.acme.dev/duun",
  "events": ["run.waiting", "run.failed", "pr.merged", "budget.threshold"],
  "status": "active",
  "secret": "whsec_q3n8vz2kd7mw4hcx9tfbr6jsya5pe1",
  "previous_secret_expires_at": "2026-11-16T12:10:00Z",
  "created_at": "2026-10-11T08:30:00Z"
}

Send a test event

POST https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}/test

Sends a signed sample event to the endpoint right away and reports your server’s response. Test events have "test": true at the top level and refer to sample objects, so they never match real runs. Needs webhooks:write.

Path parameters

endpoint_id string Required

The endpoint's id.

Body parameters

event string Optional

Which event type to send a sample of, e.g. run.waiting.

Default the endpoint's first event

curl https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT/test \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "run.waiting" }'
const delivery = await duun.webhookEndpoints.test("whe_4kQ9mT", { event: "run.waiting" });
console.log(delivery.status, delivery.response_code, `${delivery.duration_ms}ms`);
delivery = client.webhook_endpoints.test("whe_4kQ9mT", event="run.waiting")
print(delivery.status, delivery.response_code, f"{delivery.duration_ms}ms")
Response
{
  "id": "whd_t3stR9b2",
  "object": "webhook_delivery",
  "endpoint_id": "whe_4kQ9mT",
  "event_id": "evt_test8Fz1",
  "event_type": "run.waiting",
  "status": "succeeded",
  "attempts": 1,
  "response_code": 200,
  "duration_ms": 142,
  "next_attempt_at": null,
  "created_at": "2026-11-15T12:12:30Z"
}

Test deliveries aren’t retried. A failed test returns 200 with status: "failed" and your server’s response_code.

List deliveries

GET https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}/deliveries

Returns the endpoint’s deliveries from the last 7 days, newest first. Needs webhooks:read.

Path parameters

endpoint_id string Required

The endpoint's id.

Query parameters

status enum Optional

Only deliveries in this status.

One of succeeded retrying failed

event_type string Optional

Only this event type.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from the previous page.

curl "https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT/deliveries?status=failed" \
  -H "Authorization: Bearer $DUUN_API_KEY"
for await (const d of duun.webhookEndpoints.deliveries.list("whe_4kQ9mT", { status: "failed" })) {
  console.log(d.id, d.event_type, d.response_code);
}
for d in client.webhook_endpoints.deliveries.list("whe_4kQ9mT", status="failed"):
    print(d.id, d.event_type, d.response_code)
Response
{
  "object": "list",
  "data": [
    {
      "id": "whd_8Rk2pLq0",
      "object": "webhook_delivery",
      "endpoint_id": "whe_4kQ9mT",
      "event_id": "evt_2Nf7Yc0d",
      "event_type": "run.failed",
      "status": "failed",
      "attempts": 8,
      "response_code": 502,
      "duration_ms": 10000,
      "next_attempt_at": null,
      "created_at": "2026-11-14T03:12:44Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Redeliver an event

POST https://api.duun.ai/v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver

Sends the delivery’s event again, as a new delivery with the same event_id. Use it after you fix your server. Your handler should already dedupe on the event id. Needs webhooks:write.

Path parameters

endpoint_id string Required

The endpoint's id.

delivery_id string Required

The delivery to resend, from the last 7 days.

curl -X POST https://api.duun.ai/v1/webhook_endpoints/whe_4kQ9mT/deliveries/whd_8Rk2pLq0/redeliver \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
const delivery = await duun.webhookEndpoints.deliveries.redeliver("whe_4kQ9mT", "whd_8Rk2pLq0");
delivery = client.webhook_endpoints.deliveries.redeliver("whe_4kQ9mT", "whd_8Rk2pLq0")
Response
{
  "id": "whd_9Ts4mWe1",
  "object": "webhook_delivery",
  "endpoint_id": "whe_4kQ9mT",
  "event_id": "evt_2Nf7Yc0d",
  "event_type": "run.failed",
  "status": "succeeded",
  "attempts": 1,
  "response_code": 200,
  "duration_ms": 188,
  "next_attempt_at": null,
  "created_at": "2026-11-15T12:20:05Z"
}

Deliveries older than 7 days return 404 not_found.

Trigger URLs

A trigger URL starts a run in a factory workflow when something POSTs to it: CI, Sentry, a deploy hook, or anything that can send an HTTP request. Each POST starts one run, and the JSON body is passed to the first step as context.

curl -X POST https://api.duun.ai/in/acme/deploy-checks-3f1 \
  -H "Authorization: Bearer ftk_9w2hx7kq4mzv8nc3rbt6ydpa5se1" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Deploy 412 finished", "service": "payments-api"}'
Response
{ "run_id": "run_Dp1oy412" }

The call returns 202 Accepted with the new run’s id. Bodies can be up to 256 KB. A wrong or revoked token returns 401, and a deleted trigger URL returns 404.

This is different from a workflow’s Webhook trigger, which lives inside the workflow, uses an HMAC signature instead of a bearer token, and exposes the payload as {{trigger.body.*}}. See Triggers.

The trigger URL object

FieldTypeDescription
idstringUnique id, prefixed trg_.
objectstringAlways "trigger_url".
urlstringhttps://api.duun.ai/in/<workspace>/<slug>.
workflow_idstringThe workflow each POST starts a run of.
descriptionstring | nullWhat calls it.
tokenstringBearer token, prefixed ftk_. Only returned on create. Otherwise null.
last_used_atstring | nullWhen it last started a run.
created_atstringWhen it was created.

List trigger URLs

GET https://api.duun.ai/v1/trigger_urls

Returns the workspace’s trigger URLs, without tokens. Needs webhooks:read.

Query parameters

workflow_id string Optional

Only trigger URLs for this workflow.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from the previous page.

curl https://api.duun.ai/v1/trigger_urls \
  -H "Authorization: Bearer $DUUN_API_KEY"
for await (const trigger of duun.triggerUrls.list()) {
  console.log(trigger.url, trigger.workflow_id, trigger.last_used_at);
}
for trigger in client.trigger_urls.list():
    print(trigger.url, trigger.workflow_id, trigger.last_used_at)
Response
{
  "object": "list",
  "data": [
    {
      "id": "trg_3f1Ka9",
      "object": "trigger_url",
      "url": "https://api.duun.ai/in/acme/deploy-checks-3f1",
      "workflow_id": "wf_postdeploy5c",
      "description": "Post-deploy checks from the deploy pipeline",
      "token": null,
      "last_used_at": "2026-11-15T07:58:12Z",
      "created_at": "2026-10-28T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a trigger URL

POST https://api.duun.ai/v1/trigger_urls

Creates a trigger URL for a workflow. The token is returned once. Needs webhooks:write.

Body parameters

workflow_id string Required

The factory workflow each POST starts a run of.

description string Optional

What calls it, e.g. "Post-deploy checks from the deploy pipeline".

curl https://api.duun.ai/v1/trigger_urls \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "workflow_id": "wf_postdeploy5c", "description": "Post-deploy checks from the deploy pipeline" }'
const trigger = await duun.triggerUrls.create({
  workflow_id: "wf_postdeploy5c",
  description: "Post-deploy checks from the deploy pipeline",
});
// Store trigger.token now: it is only returned here.
trigger = client.trigger_urls.create(
    workflow_id="wf_postdeploy5c",
    description="Post-deploy checks from the deploy pipeline",
)
# Store trigger.token now: it is only returned here.
Response
{
  "id": "trg_3f1Ka9",
  "object": "trigger_url",
  "url": "https://api.duun.ai/in/acme/deploy-checks-3f1",
  "workflow_id": "wf_postdeploy5c",
  "description": "Post-deploy checks from the deploy pipeline",
  "token": "ftk_9w2hx7kq4mzv8nc3rbt6ydpa5se1",
  "last_used_at": null,
  "created_at": "2026-11-15T12:30:00Z"
}

Delete a trigger URL

DELETE https://api.duun.ai/v1/trigger_urls/{trigger_id}

The URL starts returning 404. Anything calling it stops starting runs. Needs webhooks:write.

Path parameters

trigger_id string Required

The trigger URL's id, e.g. trg_3f1Ka9.

curl -X DELETE https://api.duun.ai/v1/trigger_urls/trg_3f1Ka9 \
  -H "Authorization: Bearer $DUUN_API_KEY"
await duun.triggerUrls.delete("trg_3f1Ka9");
client.trigger_urls.delete("trg_3f1Ka9")
Response
{ "id": "trg_3f1Ka9", "object": "trigger_url", "deleted": true }

To change a trigger URL’s token, create a new one and delete the old one once its callers use the new URL. In the app, Rotate trigger token? in Settings → Webhooks does the same in one step.

    Type to search the docs, help center and blog.