Documentation
Practical guide to backend workflows
How Orchestrator fits into your stack — mental model, a real multi-step example, copy-paste config patterns, and a short checklist to go from zero to a running run.
Building custom integration actions? See the SDK guide for integration developers.
Mental model
Everything is a run triggered by something external or internal:
- Trigger — Webhook, schedule, manual start, or API. Hands the run an initial payload.
- Steps — HTTP calls, code, and notifications. Each step is a boundary the platform can log, retry, and inspect.
- Output — Side effects (Slack, CRM, email) plus structured records you can replay or debug.
Webhook (trigger) vs HTTP (action)
In the builder, Trigger — Incoming Webhook and Action — API Request differ by direction — who calls whom.
Webhook = RECEIVING External system ──► your workflow HTTP = SENDING Your workflow ──► external API
- Webhook — Start this workflow when an external service sends data to this URL (conceptually: data comes in). Hint: external → your workflow.
- HTTP — Send a request to an external API and use the response in your workflow (data goes out). Hint: your workflow → external API.
Example: Webhook → Code → HTTP → Slack
A CRM fires a deal.closed event. You normalize the payload in code, load extra fields from your API, then notify the team in Slack.
- 1
Webhook (trigger — incoming)
JSON like
{ deal_id, amount }enters the run as input — external system → your workflow. - 2
Code
Validate signatures, map fields, merge with defaults, or branch before any outbound call.
- 3
HTTP (action — API request)
GET or POST your internal API with
{{crm.token}}from the vault. Response JSON becomes this step's output — your workflow → external API. - 4
Slack
Post to a channel (integration step or HTTP to Slack) using
{{slack.bot_token}}— another outbound call after your data is ready.
If the CRM call times out, the run can retry that step without re-firing Slack — you fix the flaky dependency, not the whole script.
Copy-paste config pattern
HTTP steps accept JSON config. Reference vault secrets with placeholder syntax (configured in the product UI) so keys never sit in plain text.
{
"method": "POST",
"url": "https://slack.com/api/chat.postMessage",
"headers": {
"Authorization": "Bearer {{slack.bot_token}}",
"Content-Type": "application/json; charset=utf-8"
},
"body": {
"channel": "#deals",
"text": "Deal {{crm.deal_id}} closed for {{crm.amount}}"
}
}{
"method": "GET",
"url": "https://api.example.com/v1/deals/{{webhook.deal_id}}",
"headers": {
"Authorization": "Bearer {{crm.token}}"
}
}Exact placeholder names depend on how you name credentials and map prior step outputs in the builder.
When to use this
Orchestrator is aimed at teams that want serverless-style backend workflows without operating workers and queues themselves.
- API retries and chained calls — Fan-out to multiple services, handle transient failures, and keep a single run timeline.
- Backend pipelines — Normalize events, enrich data, then hand off to Slack, email, or another HTTP API.
- Scheduled jobs — Time-based triggers that run the same graph with observability per step.
- Webhook processing — Validate signatures (in code), branch on payload type, and avoid losing events when a downstream API blips.
Getting started (first run)
Follow these steps in order the first time. You can skip around later once the model clicks.
- 1
Create a workflow
Start blank or pick a template. You’re defining a graph of steps that run in order (with branches where you add logic).
- 2
Add a step
Drop your first step — often Trigger — Incoming Webhook (data in) or Action — API Request (call out). See Webhook vs HTTP.
- 3
Connect an API or add code
Chain an HTTP step to call a REST endpoint, then add a Code step when you need transforms, validation, or branching that doesn’t belong in config.
- 4
Add credentials
Store tokens and keys in the vault. Reference them by name from HTTP steps so secrets never sit in plain text in your workflow.
- 5
Publish
Save and publish the workflow so runs use the latest graph and settings.
- 6
Run and inspect outputs
Trigger a run (webhook, schedule, or manual). Open the run view to see each step’s inputs, outputs, and retries.
// One line on the whiteboard
webhook → http → code → http → done
// Each arrow is a step boundary the platform can log and retry.Core concepts
- Workflow
- The saved graph: triggers, steps, and the order they run in.
- Step
- One unit of work — for example an HTTP call or a block of code.
- Run
- A single execution of a workflow from trigger to completion (or failure).
- Credential
- A secret stored safely and injected when a step needs to authenticate.
- Artifact
- Outputs attached to a run — payloads, logs, or files a step produced for debugging or downstream use.
Step types
Trigger — Incoming Webhook
Start this workflow when an external service sends data to this URL. Think receiving: external system → your workflow.
Action — API Request (HTTP)
Send a request to an external API and use the response in your workflow. Think sending: your workflow → external API. Configure method, URL, headers, and body; map data from earlier steps.
Code step
Run small pieces of logic: normalize JSON, branch, merge fields, or glue services together.
// Code step: pick fields from prior step output
return {
userId: input.body.id,
nextUrl: env.USERS_API + "/profile",
};Debugging
- Inspect a run — Open the run timeline and expand a step to see request/response bodies and errors.
- Retry a failed step — When a transient API fails, retry without rebuilding the whole pipeline.
- Replay the workflow — Re-run with the same or edited inputs after you fix code or parameters.
// When something breaks:
// 1) Read the failing step's error + payload
// 2) Fix code or credentials
// 3) Replay and confirm the next step sees good dataWhy developers choose this
- When Zapier is too limited — You need real code, structured runs, and step-level visibility — not only happy-path automations.
- When n8n becomes messy — Large graphs are hard to reason about; this product keeps backend runs inspectable and replayable.
- When a custom backend is too much work — You get retries, logging, and execution without standing up workers, queues, and cron yourself.