Triggers
What starts a workflow run: schedules, recurring timers, mentions, issue labels, alerts, signed webhooks, events, cron and manual starts, with fields and refs.
On this page
Triggers decide what starts a run. A workflow can have several; “The workflow runs when any of these happens. Each run starts at the first step.” Triggers live on the workflow’s start node (What starts the workflow) in the Workflows tab. Select it to open the trigger editor, then use Add a trigger.
A workflow with no enabled triggers still works for manual runs, but the editor warns: “Nothing will start this workflow. Add a trigger or keep it as a draft.” A paused workflow ignores its triggers until you resume it.
Trigger kinds
The Add a trigger menu groups kinds into Time and people and From your systems.
| Kind | YAML kind | Starts a run when | Summary shown on the start node |
|---|---|---|---|
| Schedule | schedule | On chosen days at a time | “Every weekday at 9:00 AM ET” |
| Recurring | recurring | Every N minutes, hours or days | “Every 6 hours” |
| Mention | mention | Someone @mentions it from Home or any chat | “When anyone @mentions it” |
| Issue label | issue | A Linear, GitHub or Jira issue gets a label | “When a Linear issue in Platform gets “ready”” |
| Alert | alert | Sentry or Datadog crosses a threshold | “When Sentry payments-api passes 50 events/hr” |
| Webhook | webhook | Something POSTs to a signed URL | “POST to /w/wf-deploy-x1y2” |
| Event | event | A GitHub, Linear, Sentry, Stripe or Duun event fires | “On github pull_request.labeled where label == “duun"" |
| Cron | cron | A five-field cron expression matches | “Weekdays at 09:00 UTC” |
| Manual | manual | Someone starts it from New run, ⌘K, Slack /build or the API | “Manual: New run, ⌘K, Slack /build, API” |
Each trigger can be turned off without removing it. Use Remove trigger when there are two or more.
Time and people
Schedule
| Field | Notes |
|---|---|
| Days | Seven toggles, with shortcuts Every day, Weekdays and Weekends |
| Time | For example 9:00 AM |
| Time zone | ET, CT, MT, PT, UTC or another zone |
Defaults: weekdays at 9:00 AM ET. A schedule with no days is an error: “A schedule trigger has no days chosen.” Exposes {{trigger.time}}.
- { kind: schedule, days: [0, 1, 2, 3, 4], time: "09:00", zone: Europe/Lisbon }Days are numbered from Monday (0) to Sunday (6).
Recurring
Every a number of minutes, hours or days, with presets (15 or 30 minutes; 1, 2, 3, 6 or 12 hours; 1, 2 or 7 days). Default: every hour. Exposes {{trigger.time}}.
- { kind: recurring, every: 6, unit: hours }Mention
Who can start it: Anyone in the workspace or Only me. “With @ from Home or any chat, or when Duun suggests it.” Exposes {{trigger.message}} (the message that mentioned it) and {{trigger.author}}.
- { kind: mention, who: anyone }From your systems
Issue label
Starts a run when an issue gets a label, optionally only in one team and state. Needs the provider connected under Settings → Integrations & MCP.
| Field | Notes |
|---|---|
| Source | Linear, GitHub or Jira |
| Team | A team, or Any team |
| Label | Required: “An issue trigger needs a label.” |
| State | Optional, for example “Ready” |
Exposes {{trigger.issue.title}}, {{trigger.issue.url}} and {{trigger.issue.labels}}. The run is linked to the issue.
- { kind: issue, provider: linear, team: Platform, label: ready }Alert
Starts a run when a Sentry or Datadog project passes a number of events per hour. Fields: Source, Project and Threshold (events per hour). Exposes {{trigger.alert.title}}, {{trigger.alert.url}} and {{trigger.alert.count}}.
- { kind: alert, provider: sentry, project: payments-api, threshold: 50 }Webhook
Starts a run when a service POSTs JSON to the trigger’s URL, https://hooks.duun.ai/w/<path>. Copy the URL from the trigger editor.
| Field | Notes |
|---|---|
| URL | Generated, unique to this trigger |
| Signing secret | A secret from Settings → API keys & secrets that senders sign requests with |
| Sample payload | Example JSON. “Its top-level keys show up as {{trigger.body.*}} in every step.” |
Exposes {{trigger.body}} (the whole payload) and {{trigger.body.<key>}} for each top-level key of the sample. If the sample isn’t a JSON object, the editor warns: “The webhook sample payload isn’t a JSON object.”
Senders sign each request with the same scheme Duun uses for outgoing webhooks: an X-Duun-Signature header of the form t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the signing secret. Requests with a missing or wrong signature, or a timestamp more than five minutes old, are rejected and don’t start a run.
BODY='{"ref":"refs/heads/main","service":"payments-api","severity":"high"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$DEPLOY_HOOK_TOKEN" -hex | sed 's/^.* //')
curl -X POST https://hooks.duun.ai/w/wf-deploy-x1y2 \
-H "Content-Type: application/json" \
-H "X-Duun-Signature: t=$T,v1=$SIG" \
-d "$BODY"- kind: webhook
path: wf-deploy-x1y2
secret_ref: DEPLOY_HOOK_TOKEN
sample: |
{ "ref": "refs/heads/main", "service": "payments-api", "severity": "high" }The code to compute signatures in Node.js, Python and Go is in Verifying signatures.
Event
Starts a run on an event from a connected system or from Duun itself.
| Field | Notes |
|---|---|
| Source | GitHub, Linear, Sentry, Stripe or Duun |
| Event | The event name, for example pull_request.labeled. Required: “An event trigger needs an event name.” |
| Only when | Optional filter on the event payload, for example label == "duun" |
Exposes {{trigger.event.type}} and {{trigger.event.payload}}. Duun events use the same names as webhook events, so one workflow can start when another finishes, for example on run.failed.
- { kind: event, source: github, event: pull_request.labeled, filter: 'label == "duun"' }Cron
A five-field cron expression (minute, hour, day of month, month, weekday) and a time zone. “Use 5 fields: minute hour day month weekday.” The editor describes common expressions: 0 * * * * is “Every hour, on the hour”, */15 * * * * is “Every 15 minutes”, 0 9 * * 1-5 is “Weekdays at 09:00”. Anything it can’t describe reads “Custom schedule”. Exposes {{trigger.time}}.
- { kind: cron, expr: "0 6 * * 1", zone: UTC }Manual
Lets people start the workflow from New run (C), the command palette (⌘ K), Slack /build, and the API or CLI (POST /v1/runs, duun run). Who can start runs on the factory’s Access tab controls who may start manual runs.
- { kind: manual }Concurrency and duplicates
Every trigger firing starts one run. If the workflow’s Concurrent runs limit is reached, new runs queue until a slot frees up. A label added twice, or a webhook sent twice, starts two runs; for webhooks, have the sender pass a unique id and check it in the first step if duplicates matter. See Limits and budgets.
Related
- References: everything a trigger exposes to steps
- Webhooks
- Connect GitHub, Linear and Slack