Flows

Flows are multi-step automations. A trigger fires, data passes through one or more steps — actions, filters, delays, formatters, branches — and each step can read the output of the previous ones.

Core concepts

Trigger

The event that starts a flow. Triggers are either webhook (a provider posts an event to your Connect endpoint) or poll (Connect periodically checks a provider for new records). Both produce the same downstream shape: a trigger object that step steps can reference.

Step

A single unit of work. Kinds: action, filter, delay, formatter, branch. Steps run sequentially in the order you define. Each step writes its output into the execution context so later steps can reference it as {{step_N.field}}.

Action

A provider-specific operation — create a HubSpot contact, send a Slack message, enrich an email. Actions are defined by provider adapters and listed in the Actions Library.

Filter

Short-circuit a flow when a condition is false. Write the condition as an expression against the execution context — e.g. {{trigger.email}} contains "@calimaticedtech.com".

Branch

Split execution into two paths based on a condition. Each branch can hold its own chain of steps. Non-matching branches are skipped.

Templating and data passing

Every step has access to the trigger payload and the output of all prior steps via a handlebars-style template syntax:

{{trigger.email}}                // top-level trigger field
{{trigger.contact.first_name}}   // nested field
{{step_1.output.id}}             // output of step 1
{{step_2.created_at}}            // output of step 2

The template resolver supports dot notation, array indexing, and the fallback operator (||). See src/flows/services/template-resolver.tsfor the full grammar.

Building a multi-step flow

1. Go to Flows → New Flow. Name the flow and pick a trigger provider and trigger name (e.g. HubSpot → contact.created).
2. Open the flow detail page. Use the Steps tab to add actions in order. Each step needs a kind, a provider (for action steps), and an input mapping. Filter and branch steps instead take a condition_expr.
3. Switch to Canvas view to see the graph layout. Both views edit the same underlying flow_steps rows.
4. Toggle the flow active. Use the Test button to dry-run against a sample trigger payload without waiting for a real event.

Triggers: webhook vs poll

Webhook triggers subscribe to a provider event stream. When the provider POSTs to /webhook/:providerType, the trigger router dispatches to every flow that subscribes to that (provider, trigger_name) pair.

Poll triggers run on a scheduler (default every minute). Each poll call uses the subscription's last_cursor to dedupe and only pick up records seen for the first time. Subscriptions are managed at /admin/triggers or inline on a flow detail page.

Replay and testing

Every execution is stored in flow_executions. From the executions tab on a flow, or from the global Task History dashboard, you can replay a past execution — this runs the flow again with the exact same trigger payload, useful for debugging a failed run after you fix a step configuration.

Endpoints:

• POST /connect/v1/flows/:id/test — dry-run with a body-provided payload
• POST /connect/v1/flows/:id/executions/:executionId/replay — replay a past run
• GET /connect/v1/flows/:id/executions/:executionId/steps — inspect per-step output/errors

Plan limits

Flow execution consumes tasks. Every step run counts as one task. When the monthly task allowance is exhausted the engine returns HTTP 429 and halts the execution. Trigger subscriptions and template clones are also plan-gated — see Billing for your current tier's limits.