n8n integration

Pause an n8n workflow, wait for human review, and return one standard decision object.

Download and import

In n8n, create a workflow, choose Import from File, and select the downloaded JSON. Save it as Human In Circuit - Request human review.

Call it from other workflows with an Execute Sub-workflow node.

Inputs

Input	Required	Purpose
`api_key`	yes	The API key generated for this project.
`circuit_url`	yes	Use `https://humanincircuit.com`.
`n8n_public_url`	yes	Public HTTPS origin of the n8n instance.
`external_id`	no	Stable ID of the originating object; defaults to the n8n execution ID.
`inbox_key`	yes	Inbox key from Admin → Projects → your project → Inboxes.
`title`	yes	Short title displayed on the review card.
`summary`	no	One- or two-sentence card summary.
`details_markdown`	no	Longer reviewer context.
`fields`	no	Editable or read-only field definitions.
`initial_values`	no	Values keyed by each field's `key`.
`output`	no	Friendly alias for `initial_values`; useful when passing the previous node's result.
`priority`	no	`low`, `normal`, `high`, or `urgent`.
`metadata`	no	Caller-owned JSON returned unchanged by polling and callbacks.
`risk`	no	`low`, `medium`, or `high`.
`callback_auth_value`	no	Fixed secret sent back to the n8n Wait node.

Start with the complete n8n Quickstart for an example.

The API key selects the project. Configure approval, rejection feedback, rejection reasons, and undo once in Organization admin; do not pass those settings from n8n.

Callback hostname

When generating the API key:

leave Callback hostname blank for the fastest test; or
enter the n8n hostname to restrict callbacks.

For https://n8n.example.com, enter:

n8n.example.com

Do not include the protocol, port, or path.

Secure the Wait node

For production, use a fixed callback secret:

Generate a long random secret.
In the Wait node, set authentication to Header Auth.
Create a credential with the name x-human-in-circuit-token and your secret as its value.
Pass the same secret as callback_auth_value when calling the subworkflow.

The subworkflow includes auth_header and auth_value in the review request when callback_auth_value is present.

See Callback authentication for the exact request and header.

Standard output

The subworkflow returns the callback body as one object:

{
  "event_id": "<uuid>",
  "review_id": "<uuid>",
  "external_id": "<your-object-id>",
  "project_key": "content-publishing",
  "inbox_key": "article-publishing",
  "review": {
    "title": "Approve generated article",
    "fields": [],
    "initial_values": {}
  },
  "outcome": "approved",
  "original_values": {},
  "final_values": {},
  "output": {},
  "changes": [],
  "rejection_reasons": [],
  "note": "",
  "decided_at": "<iso-8601-date-time>"
}

The Execute Sub-workflow node passes this object back into the parent workflow. Add a Switch node using:

{{$json.outcome}}

Use output on the approved branch. It is the same human-approved object as final_values, which remains available for backwards compatibility. The submitted title, context, fields, and initial values are available under review. Use rejection_reasons and note on the rejected branch.

If you build the Wait node manually, n8n may place the incoming callback under $json.body. The downloadable subworkflow unwraps that envelope before it returns to the parent workflow.

Why the Wait node works

The n8n Wait node stores the paused execution in n8n's database. Human In Circuit does not keep an HTTP request open.

The subworkflow sends the Wait node's unique resume URL with the review. After the human decision is committed, Human In Circuit sends an HTTPS POST request to that URL and n8n resumes the stored execution.

Failure handling

Human In Circuit tries the callback three times: immediately, after one minute, and after five minutes.

If all attempts fail:

Open Organization admin → Health to inspect the response.
Retry the callback manually; or
use GET /v2/reviews/{review_id} to retrieve the stored result.

Common mistakes

Using a private or localhost n8n URL.
Entering a full URL in the callback hostname field.
Restricting the key to a hostname that does not match n8n's public URL.
Passing a revoked API key.
Re-running an old test execution whose Wait-node resume URL has expired.
Configuring Header Auth on the Wait node but not passing the matching callback_auth_value.

Start

Build

Integrations