Review Workflow Builder (Beta)

What is the Review Workflow Builder?

The Review Workflow Builder runs review and approval processes for you. You describe the process once as a definition, a graph of steps. Whenever something in your app needs review, you start a run against it. The engine walks the graph: it runs AI agents, waits for human approvals, evaluates branching rules, enforces deadlines, sends notifications, and tells you when the run finishes. You never build the runtime. No state machine, no retry logic, no concurrent-reviewer bookkeeping.

How it works

Author a definition. Nodes are the steps. Edges connect them. The engine validates the graph when you save it.
Start a run. Call the dispatch API, or let a webhook, cron schedule, or connected GitHub / Vercel app start it for you.
The engine executes. Agent, notification, and sync webhook steps finish without your involvement. Human steps wait for a decision.
Record decisions. Post each reviewer’s approve or reject. Matching edges fire and the run advances.
Consume the outcome. Receive signed webhooks in real time, or poll the event stream.

A minimal workflow

One reviewer approves. If they reject, the work goes back to an agent for rework.

{
  "definitionId": "doc-signoff",
  "name": "Document sign-off",
  "nodes": [
    {
      "nodeId": "manager-approval",
      "type": "human",
      "config": { "reviewers": [{ "userId": "u_manager_01", "mandatory": true }] }
    },
    {
      "nodeId": "rework-notice",
      "type": "agent",
      "config": { "agentId": "rework-agent-v1", "urlPath": "documentUrl" }
    }
  ],
  "edges": [
    { "from": "manager-approval", "to": "rework-notice", "on": "reject" }
  ]
}

That is a complete, valid workflow. Run it end to end in Setup.

Building blocks

Term	What it is
Definition	The blueprint: `nodes` + `edges` + optional `groups`. You give it a stable `definitionId`.
Node	One step. Four types: `agent`, `human`, `notification`, `webhook`.
Edge	”When this node finishes, start that one.” Carries an `on` role such as `approve` or `reject`.
Group	A set of nodes that run in parallel and share an approval quorum.
Execution	One live run of a definition. Has an `executionId` and a `steps[]` array.
Step	One runtime instance of a node inside an execution.

Definitions are versioned. Editing one creates a new version, and runs already in flight finish on the version they started with. Old versions are not readable and there is no rollback, so see Versioning before you rely on it. The graph is a DAG. Revision loops are the one exception: a reject edge pointing back to an earlier node creates a bounded retry loop. A definition holds up to 100 nodes and 500 edges.

Node types

Type	What it does	Parks in `waiting`?
`agent`	Runs a Velt agent against a URL, then routes on the result.	Yes, while the agent runs. Resumes on its own.
`human`	Waits for reviewers to approve or reject.	Yes, until you record decisions.
`notification`	Sends an email or Slack message built from the previous step’s output.	No.
`webhook`	Calls your own HTTPS endpoint.	Only in `async` mode, until your callback.

Full config for each type is in Customize Behavior.

Lifecycles

Execution:  pending → running → completed | failed | cancelled
Step:       pending → running → (waiting) → completed | failed | skipped | cancelled | breached

waiting means the step is parked. Agent steps resume on their own when the agent finishes. Human and async webhook steps stay parked until you send a decision or a callback.

Four ways to start a run

Trigger	How it starts	Setup
Dispatch API	Your backend calls `/executions/dispatch`.	Setup
Inbound webhook	An external system POSTs to the engine. Supports GitHub, Vercel, and custom signature presets.	Inbound webhook trigger
Cron schedule	A cron expression starts a run on a cadence, such as a nightly audit.	Scheduled trigger
Installed app	Connect the Velt GitHub App or Vercel Integration once, then GitHub and Vercel events route to your workflows.	App trigger

Scope

Pick the level that matches how your product is structured. Scope does not select between definitions: you always dispatch a specific definitionId, and definitions/list returns every level. Scope sets the organizationId and documentId that trigger-started runs inherit.

Level	Bound to
`apiKey`	Workspace-wide. This is the default.
`organization`	One `organizationId`.
`document`	One `documentId` under an organization.

Review Workflow Builder state is partitioned per tenant. Each tenant’s definitions, executions, and events live in that tenant’s own database.

What the engine handles for you

Parallel review with quorum. Wait for everyone, advance once N approve, or require specific people.
Idempotent dispatch. The same idempotencyKey always returns the same executionId. Retries never duplicate a run.
SLA deadlines. Set slaMs on a step. On breach the step becomes breached and routes down your escalation edge.
Signed webhooks. Every state change is POSTed with an HMAC-SHA256 signature and retried with backoff.
Recoverable events. Every event has a monotonic seq. Poll with sinceSeq to catch up after an outage.
Write-time validation. Cycles, dangling edges, unreachable nodes, and bad quorum settings are rejected before you dispatch.

Limitations in beta

You author definitions as JSON. There is no visual builder yet.
You host the reviewer UI. Render the waiting step and call recordReviewerDecision.
Setting blocking: true on an agent node is rejected at runtime. Put a human node downstream of the agent instead.
Editing a definition only affects new runs. In-flight runs are not migrated.

Get started

Setup

Author a definition, start a run, record a decision, and get the outcome.

Customize Behavior

Node config, edge routing, quorum policies, triggers, SLAs, events, and errors.

Patterns

Which option to pick, and the mistakes that look reasonable but break.

REST API Reference

Every endpoint with full request and response schemas.

Review Agents

The AI agents your agent nodes run.

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Review Workflow Builder (Beta)

What is the Review Workflow Builder?

How it works

A minimal workflow

Building blocks

Node types

Lifecycles

Four ways to start a run

Scope

What the engine handles for you

Limitations in beta

Get started

Setup

Customize Behavior

Patterns

REST API Reference

Review Agents

​What is the Review Workflow Builder?

​How it works

​A minimal workflow

​Building blocks

​Node types

​Lifecycles

​Four ways to start a run

​Scope

​What the engine handles for you

​Limitations in beta

​Get started

Setup

Customize Behavior

Patterns

REST API Reference

Review Agents

What is the Review Workflow Builder?

How it works

A minimal workflow

Building blocks

Node types

Lifecycles

Four ways to start a run

Scope

What the engine handles for you

Limitations in beta

Get started