Docs menu

Deploy and run

Durable workflows

Run multi-step jobs that call your apps, wait for events and retry until they're done, even across restarts and deploys.

Explain it

Some jobs take several steps and must finish: charge a card, wait for the warehouse, then email the customer. A workflow runs those steps for you, saves each result before the next, and picks up where it left off after a crash or a deploy.

How to do it: describe the steps (call your app, wait, retry, send an email) in project settings under Workflows, or ask your agent.

"Make a workflow that emails new users on day 1, 3 and 7."

Some jobs take more than one request and must finish: charge a card, then wait for the warehouse, then email the customer; onboard a user over three days; retry a flaky partner API until it answers. A workflow runs those steps for you. It saves every step's result before starting the next, so a run picks up where it left off after a restart, a deploy or an outage, with no queue or cron to manage.

Steps

TypeWhat it does
httpCalls one of the project's apps (service) or any url over https, and saves the status and JSON body
sleepWaits seconds (up to 30 days) without using anything
waitPauses until an event is sent to the run, or fails after timeoutSeconds

An http step retries failures (non-2xx, timeouts) retries times, three by default. The wait between tries starts at backoffSeconds (10) and doubles each time. Every try of a step carries the same Idempotency-Key header, so make the endpoint ignore a key it has already handled, and a retry can never charge twice.

Define one

API
PUT /v1/projects/:id/workflows/order
JSON
{
  "steps": [
    { "name": "charge", "type": "http", "service": "api", "path": "/charge", "body": { "order": "{{input.orderId}}", "amount": "{{input.amount}}" } },
    { "name": "shipped", "type": "wait", "event": "order.shipped", "timeoutSeconds": 604800 },
    { "name": "email", "type": "http", "service": "api", "path": "/emails/shipped", "body": { "charge": "{{steps.charge.body.id}}", "tracking": "{{steps.shipped.data.tracking}}" } }
  ]
}

Templates fill in values: {{input.x}} from the run's input, {{steps.<name>.body.x}} from an earlier HTTP step's response, {{steps.<name>.data.x}} from an event, and {{run.id}}. A value that is exactly one template keeps its type, so a number stays a number. Add "when": "{{steps.lookup.body.vip}}" to a step to skip it when the value is false, empty or missing.

Add "schedule": "0 9 * * 1" (five-field cron, UTC) to start a run on a schedule.

Run it

API
POST /v1/workflows/:id/runs {"input": {"orderId": "o_1", "amount": 1999}, "idempotencyKey": "o_1"}
POST /v1/workflow-runs/:runId/events {"name": "order.shipped", "data": {"tracking": "1Z999"}}
GET /v1/workflow-runs/:runId

The same idempotencyKey (or Idempotency-Key header) returns the existing run instead of starting another. That makes it safe to start runs from webhooks that may be delivered twice. Your app sends events to a run with its API key.

GET on a run shows each step's result and a log of every try. A failed run raises workflow_failed; fix the cause, then POST /v1/workflow-runs/:id/retry carries on from the step that failed, keeping earlier results. cancel stops a run.

Cost

Each HTTP step that runs costs a hundredth of a cent from the project's credit (the operator can change this). Sleeping and waiting are free. Agents use cli_workflow.