Workflows
Workflows connect SDK events, campaign lifecycle events, signed webhooks, integrations, conditions, AI agents, and product actions in a visual graph.
Build a workflow
- Open Dashboard → Workflows and create a blank workflow or instantiate a template.
- Add exactly one intended trigger path.
- Add action and logic nodes, then connect edges in execution order.
- Configure every node and resolve validation errors.
- Save the draft.
- Publish only after testing the trigger and external dependencies.
Draft edits do not alter the published runtime until you publish again. Unpublishing stops new trigger execution while retaining the editable definition and run history.
Trigger nodes
| Trigger | Use |
|---|---|
| SDK event | React to a canonical event after analytics storage. |
| Campaign start | React to an overlay, recommendation, or chatbot campaign lifecycle event. |
| Webhook | Accept a scoped, signed POST, PUT, or PATCH request. |
| Chatbot handoff | Continue a qualified conversation through a configured 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.
Actions and logic
Current nodes include campaign actions, governed HTTP actions, integration actions, external/internal AI agents, conditions, delays/loops where supported by the runtime templates, and product-specific operations.
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/audience rules, or ignore all targeting. Selected rule families are removed before the campaign's remaining ALL/ANY rules are evaluated. Active state, site ownership, consent, command expiry, overlay frequency caps, and experiment suppression are always enforced. Recommendation refreshes always respect campaign targeting.
The advanced Get ... Campaign Metadata actions only expose campaign identity and status to later workflow nodes. They do not display a campaign.
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 Workflow runs to inspect trigger context, node status, sanitized outputs, and failure details. Preserve the run ID when troubleshooting.
The current runtime focuses on event- and webhook-driven execution. It is not a general scheduler or unlimited background orchestration engine.