Workflows

Triggers

How runs start: task, data, webhook, middleware, schedule, SLA, error and retention triggers, plus API, MCP and CLI starts.

Every workflow has exactly one trigger node. Its type is also stored as the workflow's trigger_type.

Trigger	Starts a run when…	Typical use
Task Created / Received / Submitted / Updated / Completed / Rejected	a task changes state (optionally filtered)	Route, enrich or follow up on work
Data Table Event	a row is created, updated or deleted	React to data changes
Webhook	an external system POSTs to the workflow's inbound webhook	Integrations, forms, other apps
Middleware	a webhook arrives and the caller waits for the workflow's answer	Synchronous validation or enrichment
Schedule	a schedule occurrence is due	Nightly syncs, reminders, reports
Workflow Error	another workflow fails	Central error handling and alerting
Workflow SLA	a run nears or breaches its SLA	Escalation
Policy Review / Policy Executed	a retention policy review is due or an action ran	Records management

Any workflow can also be started directly — whatever its trigger — with POST /api/v1/workflows/start, the MCP tool workflows_start or usertasks workflows start:

bash

usertasks workflows start --set workflow_id=<id> --set variables:='{"invoice_number":"INV-1042","amount":12400}'
# add --set async:=true to queue the run and return immediately with a run id

Webhooks

Create an inbound webhook for the workflow (Settings → Webhooks, usertasks webhooks create <workflow-id>, or MCP). Callers POST JSON with the webhook's secret:

bash

curl -X POST "https://tasks.example.com/api/webhooks/inbound?hook=<slug>" \
  -H "Authorization: Bearer <webhook-secret>" -H "Content-Type: application/json" \
  -d '{"invoice_number":"INV-1042","amount":12400,"vendor_id":"V-311"}'

The body is available as {{_raw}}, and a payload mapping can turn fields into named variables. Secrets are stored only as bcrypt hashes; rotate one with usertasks webhooks rotate <webhook-id>.

Schedules

A schedule trigger runs every_minutes, hourly, daily, weekly, monthly or once, in an IANA time zone. pg_cron checks schedules every minute and fires each occurrence exactly once; if the scheduler was down, only the most recent missed occurrence runs.

json

{ "schedule_mode": "weekly", "day_of_week": 1, "time_of_day": "07:00", "timezone": "Pacific/Auckland" }

Variables a trigger provides

Every run starts with workflow_id, workflow_name, workflow_started_at, workflow_started_by, tenant_id, task_id and trigger_type, plus the user variables' defaults and whatever the trigger or caller passes. The per-trigger variables are listed in the node reference.