Workflow Definition

A workflow is a JSON or YAML document describing HTTP steps to execute.

Structure

{
  "name": "kebab-case-name",
  "version": 1,
  "schemas": {},
  "triggers": [{"type": "http", "schema": "InputSchema"}],
  "steps": {}
}

Field	Required	Description
name	Yes	Lowercase kebab-case identifier
version	Yes	Positive integer
schemas	No	Named JSON Schema definitions
triggers	Yes	Array of trigger configs
steps	Yes	Object of step definitions

Steps

"charge": {
  "after": ["validate"],
  "when": "steps.validate.response.status == 200",
  "request": {
    "method": "POST",
    "url": "https://api.stripe.com/v1/charges",
    "headers": {"authorization": "Bearer {{ secrets.STRIPE_KEY }}"},
    "body": {"amount": "{{ steps.validate.response.body.total }}"}
  },
  "retry": {"on": [500, 502, 503], "max": 3},
  "compensate": {
    "method": "POST",
    "url": "https://api.stripe.com/v1/refunds"
  }
}

Field	Description
after	Step IDs this step depends on
when	Expression that must be true to execute
request	HTTP request (method, url, headers, body)
response	Response config (timeout, schema)
retry	Retry on status codes with backoff
compensate	Rollback request if later step fails
wait	Pause for external signal
strategy	Fan-out, batch, race, or scatter

Patterns

Linear chain: Steps execute in sequence via after.

Parallel branches: Multiple steps with the same after run concurrently.

Fan-out: Process a list with bounded concurrency:

"strategy": {"type": "fan_out", "over": "steps.get.response.body.items", "concurrency": 5}

Wait for signal: Pause until an external event:

"wait": {"signal": "approved", "timeout": "24h", "on_timeout": "reject"}

Trigger validation: Reference a schema to validate input:

"triggers": [{"type": "http", "schema": "OrderInput"}]