Workflows

A workflow chains steps that would otherwise be separate API calls - verify a user, send a contract, take a payment - into one definition you can trigger and monitor. You build it once, publish it, then start runs against it.

Lifecycle

DRAFT --(publish)--> PUBLISHED --(start run)--> runs

• A new workflow starts in DRAFT. Only drafts can be edited: PUT changes a draft's name, description, or graph, and published workflows are immutable.
• publish moves a draft to PUBLISHED so it can be run. For a webhook-triggered workflow it also generates the trigger token and signing secret.
• fork copies a system template, or one of your own workflows, into a new draft. This is how you start from a template instead of a blank graph.
• delete only works on a workflow with no runs, so run history can never be orphaned.

GET /workflows returns your own workflows plus the UrbanPayX system templates you can fork.

Triggering a run

Two ways in: POST /workflows/{definition_id}/runs starts a run directly with input data you supply, and a webhook trigger lets an external system start one. See Workflow Triggers for the signing scheme, and Workflow Runs for watching and repairing runs after they start.

POST /workflows/{definition_id}/trigger-secret mints a fresh HMAC signing secret and returns it in trigger_secret once. Use it right after publishing to reveal the secret, or later to rotate one that leaked. The previous secret stops working immediately.

In this section