Creating Workflows

This guide walks you through building your first workflow — from trigger to execution and monitoring.

Prerequisites

You’ll need a KnoxCall account and a basic understanding of APIs (HTTP requests, JSON).

Workflow executions consume a metered monthly operations quota (each run counts nodes against your tenant limit; AI nodes count ×3). When the limit is reached, an execution is recorded as failed without running. Workflow access and connection/AI limits also depend on your plan.

Step 1: Create a New Workflow

Navigate to Workflows in the sidebar.
Click + Create Workflow.
Enter a name, optional description, and optional environment.
Click Create.

You’ll see the builder with an empty canvas and a trigger node. Prefer a head start? Click Templates and pick a starter — it lands as a disabled draft. See Templates.

Step 2: Configure the Trigger

Click the trigger node to configure it.

Manual Trigger (recommended for your first workflow)

Trigger Type: Manual

Run the workflow on demand from the UI or API.

Webhook Trigger

Trigger Type: Webhook
Method: POST

Publishing the workflow gives you a signed URL of the form https://api.knoxcall.com/hooks/wf/{token} to POST to.

Route Event Trigger

Trigger Type: Route Event      # underlying triggerType: proxy_event
Event Types:                   # e.g. request.completed
Route Filter: (optional)

Fires when requests pass through your routes. Valid event types are request.received, request.success, request.error, request.client_error, request.server_error, request.timeout, and request.completed. For schedule, inbound-webhook, and app-based triggers, see Triggers.

Step 3: Add an HTTP Request Node

Click the + on the trigger node’s output.
Select HTTP Request.
Configure it:

Name: Fetch User Data
Method: GET
URL: https://jsonplaceholder.typicode.com/users/1
Headers:
  Content-Type: application/json

This calls a free test API that returns a user record.

Calling one of your own routes? Switch the node’s target from URL to Route and pick the route. KnoxCall then calls it with a short-lived workflow credential and identifies itself as the platform-managed KnoxCall Workflows client — so if that route’s environment only accepts authorized clients, assign “KnoxCall Workflows” to the environment (Route → Clients tab) and the step is allowed through. Typing a *.knoxcall.com URL into a URL-mode node is refused: KnoxCall never sends workflow traffic back to itself.One-time setup: Route mode uses a workflow data-plane credential that a tenant owner or admin provisions once per mode, with POST /admin/workflows/internal-key (Live and Test are independent, so provision each mode you run in). Until it exists, a Route-mode step fails with a message saying exactly that, rather than calling anything.

Step 4: Add a Code Block Node

The Code Block runs real JavaScript in a secure sandbox.

Click the + on the HTTP Request node and select Code Block.
Name it “Transform Data”.
Enter the code:

// `input` is the upstream node's output (the HTTP Request).
// For an HTTP Request node the response body is under `input.body`.
const user = input.body;

return {
  id: user.id,
  fullName: user.name,
  email: user.email,
  company: user.company.name
};

A Code Block receives the upstream node’s output directly as the global input (for a single incoming edge). For fan-in (multiple incoming edges), input is an array of { nodeId, output } entries keyed by node id. The sandbox has no network, filesystem, or timer access.

console.log() works. Anything a script prints appears as Console output above the step’s result — in the node’s Test tab while you’re writing it, and in the Run Log for any run afterwards. Long output is capped, and the panel says when lines were dropped.

A value the run resolved from {{secrets.NAME}} is masked on the way to storage and shows as [REDACTED]. That masking works by matching the resolved secret values, so it does not cover a credential your script builds or fetches itself — those print verbatim and are stored with the step. Treat step output as readable by anyone on your team who can open the run.

Step 5: Add a Condition Node

Click the + on the Code Block node and select Condition.
Configure:

Name: Check User ID
Logic: AND
Conditions:
  - Type: equals
    Path: $.id
    Value: 1

Condition nodes evaluate a structured list of conditions (each a type, a JSONPath path, and a comparison value) combined with logic (AND/OR). The node activates its True or False outgoing edge; the other branch is recorded as skipped and greyed on the canvas.

Step 6: Add Nodes to Each Branch

True path

Add a Code Block on the Condition’s True output, name it “Success Response”:

// The Condition node passes its evaluated data through as `input.input`.
return { status: 'success', message: 'User verified!', data: input.input };

False path

Add a Code Block on the Condition’s False output, name it “Error Response”:

return {
  status: 'error',
  message: 'User verification failed',
  received_id: input.input.id
};

Step 7: Save & Publish

Autosave keeps your draft current as you edit — the draft does not affect live runs.
Click Publish to validate the graph, snapshot version 1, and make it live.

Your workflow should look like this:

[Trigger]
    ↓
[Fetch User Data] (HTTP Request)
    ↓
[Transform Data] (Code Block)
    ↓
[Check User ID] (Condition)
    ↓ True        ↓ False
[Success]       [Error]

Step 8: Test Your Workflow

Test a single node

Open a node’s Test tab in the inspector to dry-run just that node with real secrets and see its (redacted) output — without running the whole graph.

Run the whole workflow

Click Run.
Optionally add trigger input:

{ "test": true }

Watch each node highlight as it executes: green on success, red on error, with per-node timing. Open the Run Log to inspect each step’s input/output.

Step 9: Enable the Workflow

Toggle Enabled to ON. For webhook and app triggers, publishing registers the delivery endpoints described in Triggers.

Using Variables

Reference data anywhere with {{ ... }} expressions across these namespaces:

{{fetch_user_data.body.id}}   # any node's output, by node id
{{trigger.data.user_id}}      # the trigger's output (also {{trigger-node.*}})
{{input.foo}}                 # the current node's direct input
{{loop.item}}  {{loop.index}} # inside a Loop body
{{vars.counter}}              # a value set by a Set Variable node
{{secrets.API_KEY}}           # a stored secret, injected at runtime
{{env.REGION}}                # an environment variable for the active environment

Unknown names are left literal. For an HTTP Request node the response fields are status, statusText, headers, body, url, method, and success.

Secrets

Inject stored secrets into any templated field — headers, URLs, bodies, or an app connection — with {{secrets.NAME}}:

Name: Create Record
Method: POST
URL: https://api.example.com/records
Headers:
  Authorization: "Bearer {{secrets.PARTNER_API_KEY}}"
Body:
  name: "{{transform_data.fullName}}"

The value is resolved from your tenant’s secret store (scoped to the active environment) at runtime and never appears in step logs or the run overlay — it shows as [REDACTED]. For provider integrations, prefer a saved Connection over a raw HTTP Request.

Arranging the Canvas

A workflow you can read is a workflow you can debug.

Auto Layout (toolbar) re-lays the whole graph left-to-right: the trigger on the left, each step one column right of the last step that feeds it, and siblings stacked without overlapping. Loop bodies and branches keep their shape, and a node nothing reaches still gets its own space rather than being piled on top of the graph.
Align and distribute: select two or more nodes (drag a box, or Ctrl/Cmd-click), right-click one of them, and choose Align left / center / right / top / middle / bottom. With three or more selected you also get Distribute horizontally / vertically, which spreads them evenly between the two outermost nodes and leaves those two where they are.

Both are one undo step — Ctrl+Z puts every node back where it was.

More Nodes

Loop over an array

Name: Process Items
Loop Type: array
Max Iterations: 100
Array Config:
  Array Path: $.items
  Batch Size: 1

Inside the body, reference the current element with {{loop.item}} and its position with {{loop.index}}. The body is a full subgraph — branches and nested loops are allowed.

Delay

Name: Wait Before Retry
Duration: 5
Unit: seconds        # seconds, minutes, hours, or days

Long delays are durable — the run suspends and resumes on time, even across a worker restart. Anything over 30 seconds parks the run rather than holding a worker, so a three-day wait costs nothing while it waits. Two places cannot park a run: Run step test (there is no run to suspend) and a Loop set to process batches in parallel. A long delay there waits 30 seconds instead, and says so on the step output as delayClamped with the duration you asked for — it is never silently shortened. Set the loop’s batch size to 1 if its body needs a real wait.

Error Handler

Place an Error Handler downstream of a node that might fail and choose a strategy (continue, retry, or fallback); retries are durable with backoff.

// In a Code Block after the Error Handler. The caught error is on the input.
return { error_logged: true, original_error: input.originalError };

AI step

Add an AI node to classify, extract, summarize, or generate with structured output. See AI in Workflows.

Sticky Notes

Leave notes on the canvas for whoever opens the workflow next — who owns it, why a branch exists, what a vendor’s API quirk is.

Add one: right-click an empty spot on the canvas and choose Add sticky note.
Write in it: double-click the note. Markdown works — headings, bold, lists, tables, links. Ctrl+Enter (Cmd+Enter on macOS) or clicking away saves; Escape discards the edit.
Move and resize: drag the note; select it to show resize handles.
Remove one: select it and press Delete, or right-click it and choose Delete note. Undo brings it back.

Notes are annotations, not steps: nothing connects to them and they never run. They’re saved with the workflow and included when you publish, and anyone in your organization who can open the workflow can read them. Raw HTML and images in a note are not rendered, and links open in a new tab.

Never paste a credential into a note — use a Secret. Saving refuses a workflow whose note contains something that looks like one (an API key with a known prefix, a private key), just as it would in a step’s configuration.

A workflow can hold up to 100 notes of up to 4,000 characters each.

Versioning & Rollback

The workflow you edit is a draft; Publish snapshots a new version and makes it live. Open the Versions tab to see every version, and click Restore on any prior version — it loads into your draft so you can review before publishing.

Troubleshooting

A variable renders literally (e.g. `{{foo.bar}}`)

The referenced node hasn’t run yet on this path, or the name/path is wrong. Check the node id and the dot-path against the node’s actual output in a sample run. Unknown names are intentionally left as-is rather than becoming undefined.

”HTTP Request failed” / `ECONNREFUSED`

The target is unreachable. Verify the URL, confirm auth, and ensure the API is reachable from the internet.

A branch never runs

The upstream Condition/Router isn’t activating that edge. Confirm the condition type matches the value’s type and the JSONPath path resolves as expected; skipped branches are greyed on the canvas.

Best Practices

Name nodes descriptively.
Use connections and {{secrets.*}} instead of hard-coding credentials.
Add error handlers on external calls.
Test per-node before running the whole graph.
Keep workflows focused — one purpose each.

Next Steps

Workflows Overview

Concepts, node catalog, and execution model

Connections

Connect apps like Slack and Stripe

Triggers

Schedule, webhook, and app triggers

Using the API

Manage and run workflows via /v1

Statistics

Level: beginner
Time: 12 minutes

​Creating Workflows

​Prerequisites

​Step 1: Create a New Workflow

​Step 2: Configure the Trigger

​Manual Trigger (recommended for your first workflow)

​Webhook Trigger

​Route Event Trigger

​Step 3: Add an HTTP Request Node

​Step 4: Add a Code Block Node

​Step 5: Add a Condition Node

​Step 6: Add Nodes to Each Branch

​True path

​False path

​Step 7: Save & Publish

​Step 8: Test Your Workflow

​Test a single node

​Run the whole workflow

​Step 9: Enable the Workflow

​Using Variables

​Secrets

​Arranging the Canvas

​More Nodes

​Loop over an array

​Delay

​Error Handler

​AI step

​Sticky Notes

​Versioning & Rollback

​Troubleshooting

​A variable renders literally (e.g. {{foo.bar}})

​”HTTP Request failed” / ECONNREFUSED

​A branch never runs

​Best Practices

​Next Steps

Workflows Overview

Connections

Triggers

Using the API

Statistics

Tags

Creating Workflows

Prerequisites

Step 1: Create a New Workflow

Step 2: Configure the Trigger

Manual Trigger (recommended for your first workflow)

Webhook Trigger

Route Event Trigger

Step 3: Add an HTTP Request Node

Step 4: Add a Code Block Node

Step 5: Add a Condition Node

Step 6: Add Nodes to Each Branch

True path

False path

Step 7: Save & Publish

Step 8: Test Your Workflow

Test a single node

Run the whole workflow

Step 9: Enable the Workflow

Using Variables

Secrets

Arranging the Canvas

More Nodes

Loop over an array

Delay

Error Handler

AI step

Sticky Notes

Versioning & Rollback

Troubleshooting

A variable renders literally (e.g. `{{foo.bar}}`)

”HTTP Request failed” / `ECONNREFUSED`

A branch never runs

Best Practices

Next Steps