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
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed whe_. |
object | string | Always "webhook_endpoint". |
url | string | Your public https:// URL. |
events | string[] | Event types it receives, e.g. run.waiting. |
description | string | null | Helps teammates know what it feeds. |
status | enum | active, paused (no events are sent) or failing (every delivery has failed for 24 hours; Duun keeps trying new events). |
secret | string | The signing secret, prefixed whsec_. Only returned when the endpoint is created or its secret is rotated. Otherwise null. |
created_at | string | When it was created. |
{
"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
| Event | When it fires |
|---|---|
run.started | A run begins |
run.waiting | A run needs a human |
run.failed | A run failed after retries |
run.succeeded | A run finished green |
ask.created | A new ask lands in someone’s inbox |
ask.resolved | An ask was approved, answered or declined |
pr.opened | An agent opened a pull request |
pr.merged | A pull request was merged |
budget.threshold | Spend passed a budget threshold |
machine.created | A new sandbox or computer was created |
The delivery object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed whd_. Sent as the X-Duun-Delivery header. |
object | string | Always "webhook_delivery". |
endpoint_id | string | The endpoint it was sent to. |
event_id | string | The event, prefixed evt_. Redeliveries of the same event share it. |
event_type | string | E.g. run.waiting. |
status | enum | succeeded, retrying or failed. |
attempts | integer | Attempts so far. |
response_code | integer | null | Your server’s last status code. null for timeouts and connection errors. |
duration_ms | integer | null | How long your server took on the last attempt. |
next_attempt_at | string | null | When the next retry is scheduled, while retrying. |
created_at | string | When the first attempt was made. |
Deliveries are kept for 7 days.
Endpoints
List webhook endpoints
https://api.duun.ai/v1/webhook_endpoints Returns the workspace’s outgoing endpoints. Needs webhooks:read.
Query parameters
-
statusenum Optional -
Only endpoints in this status.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom 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)){
"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
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
-
urlstring Required -
A public
https://URL, e.g.https://hooks.acme.dev/duun. Private and loopback addresses are refused. -
eventsstring[] Required -
At least one event type from the list above.
-
descriptionstring 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.{
"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_requestwithparam: "url"for non-https, private or loopback URLs.400 invalid_requestwithparam: "events"for an empty list or an unknown event type.
Retrieve a webhook endpoint
https://api.duun.ai/v1/webhook_endpoints/{endpoint_id} Returns one endpoint, without its secret. Needs webhooks:read.
Path parameters
-
endpoint_idstring 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
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_idstring Required -
The endpoint's id.
Body parameters
-
urlstring Optional -
A new public
https://URL. -
eventsstring[] Optional -
Replaces the list. At least one.
-
descriptionstring Optional -
Helps teammates know what it feeds.
-
statusenum Optional -
Pause or resume.
failingis set by Duun and can't be sent.
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"],
){
"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
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_idstring 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"){ "id": "whe_4kQ9mT", "object": "webhook_endpoint", "deleted": true }Rotate the signing secret
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_idstring Required -
The endpoint's id.
Body parameters
-
expire_afterenum Optional -
How long the old secret keeps signing deliveries.
nowstops using it at once.
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{
"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
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_idstring Required -
The endpoint's id.
Body parameters
-
eventstring Optional -
Which event type to send a sample of, e.g.
run.waiting.
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"){
"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
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_idstring Required -
The endpoint's id.
Query parameters
-
statusenum Optional -
Only deliveries in this status.
-
event_typestring Optional -
Only this event type.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom 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){
"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
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_idstring Required -
The endpoint's id.
-
delivery_idstring 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"){
"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"}'{ "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
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed trg_. |
object | string | Always "trigger_url". |
url | string | https://api.duun.ai/in/<workspace>/<slug>. |
workflow_id | string | The workflow each POST starts a run of. |
description | string | null | What calls it. |
token | string | Bearer token, prefixed ftk_. Only returned on create. Otherwise null. |
last_used_at | string | null | When it last started a run. |
created_at | string | When it was created. |
List trigger URLs
https://api.duun.ai/v1/trigger_urls Returns the workspace’s trigger URLs, without tokens. Needs webhooks:read.
Query parameters
-
workflow_idstring Optional -
Only trigger URLs for this workflow.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom 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){
"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
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_idstring Required -
The factory workflow each POST starts a run of.
-
descriptionstring 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.{
"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
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_idstring 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"){ "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.
Related
- Webhooks, Event catalog and Verifying signatures
duun webhooks listento forward events to your machine while you build a handler- Webhook deliveries are failing in the help center