Skip to main content

​
Workflows

Workflows are the core building block of HITL.sh. A workflow is a visual pipeline that defines how data flows from a trigger through processing steps — including human review — to produce a result. You build workflows in the workflow designer using a drag-and-drop canvas.

​
What is a Workflow?

A workflow in HITL.sh is a directed graph of nodes that:
  • Starts with a trigger: Receives data via a webhook URL
  • Processes data through nodes: AI, human review, conditions, transforms, and actions
  • Produces responses: Human decisions captured during execution
  • Tracks executions: Every run is logged with its inputs, outputs, and status
Workflows replace the previous loop + API request model. Instead of creating loops and sending requests via code, you design a visual workflow in the dashboard and trigger it with a webhook.

​
Node Types

Every workflow is built from these node types:
The entry point for every workflow. Each workflow has a unique webhook URL. When you send a JSON payload to that URL, a new execution starts.
  • Automatically generated when you create a workflow
  • Accepts any JSON body — the payload is available to all downstream nodes
  • Supports optional authentication headers
Pauses execution and sends the item to human reviewers for a decision. This is the core of HITL.sh.
  • Response types: text, single select, multi select, rating, number, boolean, editable text
  • Reviewers: Assign individuals or groups from your Humans directory
  • Fan-out mode: Send to multiple reviewers in parallel and collect all responses
  • Endorsement mode: Require a minimum number of approvals before proceeding
  • Timeout: Set a deadline with a default response as fallback
Runs an AI prompt against the execution data. Use this for classification, summarization, extraction, or any LLM task before or after human review.
  • Configure a system prompt and user prompt with template variables
  • Select a model (GPT-4o, Claude, etc.)
  • Output is added to the execution context for downstream nodes
Branches execution based on data values. Supports two modes:
  • If/Else: Evaluate a single boolean expression and branch into two paths
  • Switch: Match a value against multiple cases, each with its own downstream path
Use conditions to route data to different reviewers, skip steps, or handle edge cases.
Modify or reshape data between nodes. Use transforms to:
  • Extract fields from the trigger payload
  • Format text for human reviewers
  • Combine outputs from multiple nodes
  • Map data into the shape expected by an action node
Performs a side effect at the end of a branch — sending an email, calling an external API, updating a database, or posting to Slack. Actions are the “output” of your workflow.

​
How Workflows Execute

When a webhook payload hits your workflow’s trigger URL, HITL.sh creates an execution and processes nodes in order:
1

Trigger fires

The incoming JSON payload is captured and the execution begins.
2

Nodes run in sequence

Each node processes its input and passes output to connected downstream nodes. AI nodes run automatically; human review nodes pause and wait.
3

Human review pauses execution

When a human review node is reached, the assigned reviewers receive a notification on the mobile app and web dashboard. The execution waits until a response is submitted (or the timeout is reached).
4

Execution completes

Once all branches have resolved, the execution is marked as completed. Results are available in the Executions tab and via the API.

​
Webhook Triggers

Every workflow has a unique webhook URL in this format:
Send a POST request with a JSON body to start an execution:
The JSON body is available to all nodes in the workflow as the trigger payload.

​
Workflow States

Workflows have two states:

Draft

The workflow is being designed. You can edit nodes, connections, and settings. It will not respond to webhook triggers.

Active

The workflow is live. Webhook triggers create new executions. Editing is locked until you deactivate.

​
Best Practices

Start Simple

Begin with a trigger, one human review node, and one action. Add complexity only when needed.

Use Conditions for Routing

Route high-priority items to senior reviewers and low-priority items to standard reviewers using condition nodes.

Set Timeouts

Always configure timeouts on human review nodes with safe default responses to prevent executions from stalling.

Test Before Activating

Use the workflow designer’s test mode to send sample payloads and verify your pipeline end-to-end before going live.

​
Next Steps

Create Your First Workflow

Step-by-step guide to building and activating your first workflow

Workflow Designer

Learn the designer interface — canvas, nodes, and configuration

Responses

Understand how human review responses work within workflows

Humans

Set up your Universe, Groups, and People for reviewer assignment