Webhooks
Send run, ask, pull request and budget events to your own services, and start runs from outside Duun with trigger URLs and workflow webhook triggers.
On this page
Webhooks connect Duun to the rest of your stack in both directions. Outgoing endpoints tell your services when something happens in a run: an agent is waiting on a person, a pull request merged, a budget crossed a threshold. Incoming trigger URLs and workflow Webhook triggers let CI, deploy hooks, Sentry or any HTTP client start runs.
Everything on this page can be set up in Settings → Webhooks. The same objects are available through the webhook endpoints API and the CLI, both of which are in Preview.
Four ways to move data over HTTP
Duun has four HTTP features that sound alike. Pick by direction and by what should happen.
| Feature | Direction | Where you set it up | What it does | Authentication |
|---|---|---|---|---|
| Endpoint | Duun → you | Settings → Webhooks → Endpoints | Delivers events such as run.waiting or pr.merged to your URL | Duun signs each request with X-Duun-Signature (HMAC-SHA256, whsec_ secret) |
| Trigger URL | You → Duun | Settings → Webhooks → Incoming triggers | Each POST starts one run in a factory workflow; the JSON body becomes the run’s context | You send Authorization: Bearer ftk_… |
| Webhook trigger | You → Duun | A workflow’s start node: Add a trigger → Webhook | Starts that workflow; top-level keys of the payload become {{trigger.body.*}} references | You sign with a secret from API keys & secrets, same X-Duun-Signature scheme |
| Send to URL step | Duun → you, mid-run | A step in the workflow editor | Posts a JSON body you write (with references and secrets) at a specific point in a run | Headers you choose, for example a bearer token from {{secrets.DEPLOY_HOOK_TOKEN}} |
Rules of thumb:
- Use an endpoint when you want to know about runs across the whole workspace, for example to update a status page or page someone when a run fails after retries.
- Use a trigger URL when a system that can only send a bearer token (most CI and deploy tools) should start work.
- Use a Webhook trigger when the incoming payload has fields steps should read by name. See Triggers.
- Use a Send to URL step when one workflow needs to call out at a known point, with a payload shaped from earlier step outputs. See Step kinds.
Create an endpoint
- Open Settings → Webhooks and choose New endpoint under Endpoints.
- Enter a public
https://URL, for examplehttps://hooks.acme.dev/duun. Private network addresses and plainhttp://are rejected. - Pick at least one event. Picking an event from Available events starts the form with that event selected.
- Add an optional description so teammates know what the endpoint feeds.
- Save, then copy the signing secret from Save your signing secret. It starts with
whsec_and is shown only once. Store it in your secret manager.
You can create the same endpoint with the API. The response is the only time the secret is returned.
curl https://api.duun.ai/v1/webhook_endpoints \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: 6f1c2a90-3b1e-4c55-9d1a-0b2f7e8c4d11" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.acme.dev/duun",
"events": ["run.waiting", "run.failed", "pr.merged"],
"description": "On-call bridge"
}'{
"id": "whe_2Lq8",
"object": "webhook_endpoint",
"url": "https://hooks.acme.dev/duun",
"events": ["run.waiting", "run.failed", "pr.merged"],
"description": "On-call bridge",
"status": "active",
"secret": "whsec_Q3m9vT2xK8pLr4sN7wY1zB6c",
"created_at": "2026-11-15T09:12:44Z"
}Your handler must verify the signature before trusting the body.
Test an endpoint
Send a test event. In the endpoint’s row, open the menu and choose Send test event. Duun delivers a sample of one of the endpoint’s events and shows the result inline, for example Test event delivered · 200 in 142ms or Test failed · hooks.acme.dev returned 502. Test deliveries are signed with the real secret.
Forward events to your laptop. The CLI can receive events for your workspace and forward them to a local server, so you can debug a handler without a public URL:
duun webhooks listen --forward-to http://localhost:3000/webhooks --events run.waiting,pr.mergedListening for run.waiting, pr.merged on workspace acme
Signing secret for this session: whsec_local_8Hn2Rk5Wq0Ze
Forwarding to http://localhost:3000/webhooks
12:04:31 run.waiting evt_9xYa71 → 200 38ms
12:06:02 pr.merged evt_9xYa7k → 200 41msThe secret printed by listen is temporary and only valid for that session. Use it in your local handler, not the endpoint’s production secret.
Delivery and retries
Duun treats a delivery as successful when your server answers with any 2xx status within 10 seconds. Anything else, including redirects, 4xx, 5xx, connection errors and timeouts, counts as a failure.
Failed deliveries retry with exponential backoff for up to 24 hours. The schedule after the first attempt is roughly:
| Attempt | Delay after the first attempt |
|---|---|
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
| 8 | 24 hours |
After the last attempt the delivery is marked failed. If every delivery to an endpoint fails for 24 hours straight, the endpoint shows Failing in Settings. Duun keeps delivering new events to a failing endpoint, so it recovers by itself once your server is back.
Ordering and duplicates. Deliveries can arrive out of order, and the same event can arrive more than once, for example when your server processed a request but timed out before answering. Make handlers idempotent: store each event’s id (evt_…) and skip ids you have already processed. Use created_at and the embedded object’s state, not arrival order, to decide what is current.
Delivery log. Open an endpoint and choose Open delivery log to see every request from the last 7 days with its status code, duration, request body and response. Choose Redeliver on any delivery to send it again with a fresh timestamp and signature. You can do the same with POST /webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver.
Pausing. Choose Pause in the endpoint menu to stop deliveries, for example during a migration. While paused, no events are sent and nothing is queued. Deleting an endpoint stops deliveries immediately and drops queued retries.
If deliveries keep failing, work through Webhook deliveries are failing.
Start runs with a trigger URL
A trigger URL starts one run in a factory workflow for each POST. Create one in Settings → Webhooks → Incoming triggers → New trigger URL, pick the factory workflow it Starts a run in, and copy the token from Save your trigger token. Tokens start with ftk_ and are shown once.
curl -X POST https://api.duun.ai/in/acme/deploy-checks-4f1 \
-H "Authorization: Bearer ftk_7Gm2Qx9Lp4Rt8Vb1" \
-H "Content-Type: application/json" \
-d '{"summary": "Deploy 412 finished", "service": "payments-api", "sha": "9c1d4e2"}'{ "run_id": "run_7f3aK2pQ" }Duun answers 202 Accepted as soon as the run is queued. The JSON body (up to 256 KB) is passed to the first step as context. A missing or wrong token returns 401, and a deleted trigger URL returns 404.
To create trigger URLs from code, use POST /trigger_urls with a workflow_id. See Webhook endpoints in the API reference.
Rotate secrets and tokens
Choose Rotate signing secret… on an endpoint, or Rotate trigger token? on a trigger URL. For endpoints you can keep the old secret valid for 1 hour or 24 hours while you deploy the new one; during that window each delivery carries two v1= signatures, one per secret. See Verifying signatures.
Best practices
- Verify every request. Check the signature and the timestamp before parsing the body. Reject anything older than 5 minutes.
- Answer fast. Return
200as soon as you have stored the event, then do slow work in a queue. Handlers that call other APIs inline are the most common cause of timeouts. - Deduplicate on
id. Expect retries and occasional duplicates. - Subscribe narrowly. Pick only the events you handle. An endpoint that ignores most of what it receives is harder to debug.
- Use one endpoint per consumer. A status page and an on-call bridge should have separate endpoints and secrets, so you can pause or rotate one without affecting the other.
- Keep secrets out of code. Store
whsec_andftk_values in your secret manager and rotate them when someone with access leaves.