Workflows
Workflows connect SDK events, form submissions, campaign lifecycle events, signed webhooks, schedules, integrations, conditions, AI agents, and product actions in a visual graph.
Build a workflow
- Open Dashboard → Workflows and select New workflow, then From template or From scratch.
- Add exactly one intended trigger.
- Select Add a step to add actions and logic, then connect steps in execution order. Tidy layout arranges the graph.
- Configure every step and resolve the items on its Issues tab.
- Test with Run, or open a step and select Test through this step. Use data from a previous run replays real trigger data.
- Save the draft, then Publish after testing the trigger and external dependencies.
Workflow cards show Ready when published, In progress for drafts, and Needs attention when validation fails. Draft edits do not alter the published runtime until you publish again. Move to Draft stops new trigger execution while keeping the editable definition and run history.
Templates
Built-in templates are a starting point you can edit before publishing:
- Recover Zero-Result Searches
- Accelerate High-Value Carts
- Refresh Product Recommendations
- Escalate Chatbot Handoffs
- Relay Purchase Conversions
- Browse Abandonment
- Checkout Abandonment
Saved merchant templates appear alongside them.
Triggers
| Trigger | Use |
|---|---|
| SDK Event Trigger | React to a canonical storefront event after analytics storage. |
| Form Submission Trigger | React to an overlay form submission. |
| Campaign Trigger | React to an overlay, recommendation, or chatbot campaign lifecycle event. |
| Webhook Trigger | Accept a scoped, signed POST, PUT, or PATCH request. |
| Schedule Trigger | Run on an interval (5 minutes to 30 days), daily, or weekly in a chosen time zone. Choose whether overlapping runs are skipped or allowed. |
| Manual Trigger | Run on demand from the builder. |
| Called by Workflow | Run as a sub-workflow from an Execute Workflow step. |
A chatbot handoff to a workflow runs the selected published workflow. SDK ingestion waits for workflow trigger queueing. If queueing fails after analytics storage, the event response can fail; a retry may be deduplicated and still attempt trigger dispatch again.
Steps
| Group | Steps |
|---|---|
| Data | Edit Fields, List Operations, Marketing Contact Lookup, Subsequent Event Check |
| Actions | Run Campaign in Browser, Internal Product Operation (upsert a product, set status, replace tags), AI Agent (OpenAI, Anthropic, or Gemini connection), HTTP Request, Integration Operation, Execute Workflow, Return to Parent, Stop Branch |
| Logic | Condition, Wait (60 seconds to 30 days), Merge Branches, For Each, Repeat N Times |
Wait is durable: the run resumes after the delay even if nothing else happens on the site.
Run a campaign in the visitor's browser
Use Run Campaign in Browser to Show overlay, Open chatbot, or Refresh recommendations for the session or device that triggered the workflow. The workflow event replaces the campaign's normal launch triggers.
Overlay and chatbot actions can respect all campaign targeting, ignore selected Page, Device, Location, or Audience and intent rules, or ignore all contextual targeting. Selected rule families are removed before the campaign's remaining ALL/ANY rules are evaluated. Saved-audience rules always apply. Active state, site ownership, consent, command expiry, overlay frequency caps, and experiment suppression are always enforced. Recommendation refreshes always respect campaign targeting.
A command can require marketing or personalization consent. It runs only when the storefront has reported that consent with setWorkflowCommandConsent(). See SDK configuration.
logic.if uses a structured condition—never JavaScript evaluation. Allowed roots are trigger, workflow, outputs, last, and loop. Operators include existence, equality, ordered comparisons, and contains/not-contains. Prototype and constructor paths are rejected.
{
"left": { "type": "path", "path": "trigger.payload.total" },
"operator": "greater_than_or_equal",
"right": { "type": "literal", "value": 50 }
}
HTTP and integration security
HTTP actions allow only http/https, block credentials in URLs, validate every redirect hop, block loopback/private/link-local/multicast/reserved targets, cap redirect count and response size, and apply a timeout.
Do not place bearer tokens or API secrets directly in a workflow graph. Choose an owned integration connection and supported auth mode. Runtime configuration is sanitized so secrets do not enter run outputs.
Signed webhook triggers
Webhook URLs are scoped to one merchant, workflow, and configured path:
/api/v1/workflows/webhooks/{merchantId}/{workflowId}/{configured-path}
Send:
X-Upsurge-Timestamp: 2026-07-11T20:00:00.000Z
X-Upsurge-Signature: <hex HMAC-SHA256>
Sign this exact string with the node signing secret:
{timestamp}.{HTTP_METHOD}.{request_pathname}.{raw_request_body}
Timestamps must be within five minutes. Missing, stale, mismatched, or cross-workflow signatures fail closed.
Publish and observe
Before publishing:
- every referenced campaign, connection, and template belongs to the workspace;
- required secrets are configured outside the graph;
- webhook path/method/signature match the sender;
- conditions use safe context paths;
- failure paths do not cause duplicate external effects.
Use Recent activity to review runs. Workflow run details shows the trigger context, a Step timeline with each step's status, sanitized outputs, and failure details. Preserve the run ID when troubleshooting.