human-in-circuit

Request and retrieve human decisions from Human In Circuit.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.0
Author: dspsolves

Documentation

Human In Circuit for n8n

Request a human decision, select a project and inbox, map the inbox's form fields, and retrieve the committed approval or rejection with the human's edited values. OAuth account sign-in and existing project API-key connections are supported.

Install

For self-hosted n8n, open Settings → Community Nodes → Install, enter n8n-nodes-human-in-circuit, review the community-node notice and install. An instance owner/admin must install the package. For queue-mode deployments, ensure every worker has the same package version. This package is not yet n8n verified; n8n Cloud installation requires verification.

Source: https://github.com/dspsolves/n8n-nodes-human-in-circuit

Help: https://humanincircuit.com/docs/integrations/n8n

Connect with OAuth

  1. Choose OAuth2 authentication and create a Human In Circuit OAuth2 API credential.
  2. Copy the credential's OAuth Redirect URL into HIC Settings → Automation connections. Register the exact HTTPS callback URL for your n8n instance.
  3. Paste the returned public Client ID into the n8n credential. No client secret is required.
  4. Choose Connect, sign in to HIC, review permissions and inbox access, then allow access. Complete this within five minutes: n8n's callback wait expires before HIC's ten-minute authorization request.
  5. Select your saved credential, then a project and inbox. Use Inbox Form provides typed fields for text, numbers, booleans, dates and choices, with fixed values or expressions. Custom Form JSON supports advanced requests.

HIC permissions remain limited by the user's role, consent and plan. Free/Lite/Pro credit limits are unchanged. Tokens refresh automatically; disconnect access in HIC Settings. Existing project API-key credentials and version 1 nodes remain supported.

Operations

Operation Behavior
Request Decision Creates a request in the selected inbox and returns its review ID. Use a stable Source Item ID for retries.
Get Decision Returns pending status or the committed decision and edited values.
Recall Decision Request Cancels a pending or undo-window request; cannot change a committed decision.

A repeated Source Item ID returns the original review without a second review credit. A different source request needs a different ID. Optional fields include priority, risk, expiry, external correlation, metadata and source information.

Only committed approved/rejected decisions are resolved. Pending, decision_pending (undo window), cancelled and expired requests are not approval. Route on outcome; use output / final_values for edited values. No node approves or rejects a request on the human's behalf.

Wait for a human decision

Import the OAuth workflow example from this public repository and choose your saved credential on both HIC nodes. Its inputs include project_id, inbox_key, title, source_item_id, content and optional values_json. The original API-key example is also available.

Run one source item per subworkflow execution. The workflow uses n8n's core Wait node at two-minute intervals and stops after 24 hours or cancellation/expiry. n8n keeps waits shorter than 65 seconds in memory; keep the interval at least 65 seconds for database persistence. The original project and review ID are retained across polls. This is a native-node workflow template, not a single callback-based wait operation.

The example returns approved and rejected decisions to its parent. Connect protected downstream actions only to the approved branch. Use effect_key with the downstream service's idempotency mechanism; if unavailable, implement a durable deduplication record before effects. The node cannot promise exactly-once effects in an arbitrary external service. A polling timeout does not cancel or approve the stored HIC request: retrieve it later by ID.

Connect with an API key

Create a Human In Circuit API credential using a v2 project-scoped key from HIC Settings. Select an inbox and configure the request. Keys belong in credentials, never workflow parameters or exports. The service origin is fixed to https://humanincircuit.com.

Troubleshooting and data

Authentication and quota failures stop execution safely. Human rejection is a normal result. Recover using the stored review ID and Source Item ID rather than creating duplicates. Polling consumes API rate-limit requests, not review credits; size concurrency accordingly.

The node does not emit debug logs. n8n stores workflow execution data according to your instance settings; restrict access and retention, and remove private data from shared exports. Never publish real request fixtures.

OAuth sign-in, project/inbox discovery, typed values including 0 and false, idempotent retry, Get, Recall, rotating refresh and an almost-eight-hour persisted wait returning edited output passed hosted acceptance on n8n 2.46.6. See acceptance notes. Verification by n8n is a separate review.

Development

Node 22+: npm ci --ignore-scripts, npm run build, npm run lint, npm test, npm pack --dry-run. npm run dev starts a local n8n development instance. Runtime dependencies are limited to n8n's peer API. Publish through this repository's GitHub Actions workflow with npm provenance.

MIT applies to this package only.

Discussion