n8n Integration Guide

Learn how to use ViaHuman with n8n workflows to add human-in-the-loop approvals.

Prerequisites

  • An n8n instance (self-hosted or cloud)
  • A ViaHuman account with an API key
  • Basic knowledge of n8n workflows

Installation

Option 1: Install via n8n UI (Recommended)

  1. Open your n8n instance
  2. Go to Settings → Community Nodes
  3. Click Install
  4. Enter: n8n-nodes-viahuman
  5. Click Install
  6. Restart n8n

Option 2: Manual Installation

cd ~/.n8n/custom
npm install n8n-nodes-viahuman

Then restart your n8n instance.

Setting Up Credentials

  1. In your n8n workflow, add a ViaHuman node
  2. Click on Credentials → Create New
  3. Fill in the following:
    • API Key: Your ViaHuman API key (starts with vh_live_)
    • API URL: https://api.viahuman.xyz (or your custom domain)
  4. Click Save

Operations

The ViaHuman n8n node supports three operations:

1. Create Approval

Creates a new approval request and optionally waits for the response.

Required Parameters:

  • Title: Title of the approval request
  • Description: Detailed description (optional)

Optional Parameters:

  • Actions: Comma-separated list of actions (default: "approve,reject")
  • Input Type: Type of input requested (none, text, number, select, image)
  • Timeout: Seconds to wait before timing out (default: 3600)
  • Wait for Response: Whether to block the workflow until user responds
  • Polling Interval: Seconds between status checks (default: 5)

2. Get Approval

Fetches the current status of an approval request.

Required Parameters:

  • Approval ID: The UUID of the approval request

3. Cancel Approval

Cancels a pending approval request.

Required Parameters:

  • Approval ID: The UUID of the approval request

Example Workflows

AI Email Review Workflow

[Gmail Trigger: New Email]
    ↓
[OpenAI: Generate Response]
    ↓
[ViaHuman: Create Approval]
    - Title: "Review AI Email"
    - Input Type: Text
    - Default Value: {{ $json.ai_response }}
    - Wait for Response: true
    ↓
[IF Node: {{ $json.response_action }} === "approve"]
    ↓ (Yes)
[Gmail: Send Reply]
    - Body: {{ $json.response_input }}
    ↓ (No)
[Stop]

Budget Approval Workflow

[Webhook Trigger: Budget Request]
    ↓
[ViaHuman: Create Approval]
    - Title: "Approve Budget: {{ $json.project_name }}"
    - Input Type: Number
    - Min: 0
    - Max: 10000
    - Currency: USD
    - Default Value: {{ $json.requested_amount }}
    - Wait for Response: true
    ↓
[IF Node: {{ $json.response_action }} === "approve"]
    ↓ (Yes)
[Stripe: Create Payment]
    - Amount: {{ $json.response_input }}
    ↓ (No)
[Slack: Send Rejection Notice]

Deployment Gate Workflow

[GitHub Trigger: New Release]
    ↓
[ViaHuman: Create Approval]
    - Title: "Deploy {{ $json.release_name }}?"
    - Input Type: Select
    - Options: [
        {"value": "staging", "label": "Deploy to Staging"},
        {"value": "production", "label": "Deploy to Production"},
        {"value": "cancel", "label": "Cancel Deployment"}
      ]
    - Wait for Response: true
    ↓
[Switch Node: {{ $json.response_input }}]
    ↓ (staging)
[Deploy to Staging]
    ↓ (production)
[Deploy to Production]
    ↓ (cancel)
[Stop]

Input Types

None

Simple approve/reject with no additional input.

{
  "input_type": "none"
}

Text

Allow user to input or edit text.

{
  "input_type": "text",
  "input_config": {
    "placeholder": "Enter your text...",
    "multiline": true,
    "max_length": 500,
    "default_value": "{{ $json.initial_text }}",
    "required": true
  }
}

Number

Allow user to input a number (e.g., budget amount).

{
  "input_type": "number",
  "input_config": {
    "label": "Amount",
    "min": 0,
    "max": 10000,
    "step": 100,
    "currency": "USD",
    "default_value": 1000,
    "required": true
  }
}

Select

Allow user to choose from predefined options.

{
  "input_type": "select",
  "input_config": {
    "label": "Choose environment",
    "options": [
      {"value": "dev", "label": "Development", "description": "Dev environment"},
      {"value": "staging", "label": "Staging", "description": "Staging environment"},
      {"value": "prod", "label": "Production", "description": "Live production"}
    ],
    "required": true
  }
}

Image

Allow user to upload an image.

{
  "input_type": "image",
  "input_config": {
    "required": true
  }
}

Using Response Data

After an approval is completed, the ViaHuman node outputs:

{
  "id": "approval-uuid",
  "status": "approved",
  "response_action": "approve",
  "response_input": "User's input value",
  "response_comment": "Optional comment",
  "responded_at": "2024-12-15T10:30:00Z"
}

Access these values in subsequent nodes:

  • {{ $json.response_action }} - Which action was taken
  • {{ $json.response_input }} - User's input value
  • {{ $json.response_comment }} - User's optional comment
  • {{ $json.status }} - Final status (approved, rejected, timeout, cancelled)

Troubleshooting

Node doesn't appear in n8n

  1. Ensure the package is installed: npm list n8n-nodes-viahuman
  2. Restart your n8n instance completely
  3. Check n8n logs for errors: N8N_LOG_LEVEL=debug n8n start

"Invalid API key" error

  1. Verify your API key starts with vh_live_
  2. Check the API URL is correct: https://api.viahuman.xyz
  3. Ensure the key is active in your dashboard

Workflow hangs on ViaHuman node

  1. Check "Wait for Response" is enabled
  2. Verify your mobile app is logged in
  3. Check the timeout value (default: 3600 seconds = 1 hour)
  4. Look at the approval in your mobile app or dashboard

Not receiving push notifications

  1. Ensure you're logged into the mobile app
  2. Check notification permissions are enabled
  3. Verify your push token is saved (check in app settings)
  4. Try logging out and back in to refresh the push token

Best Practices

  1. Set reasonable timeouts: Don't make workflows wait indefinitely
  2. Handle rejections: Always have a branch for rejected approvals
  3. Add context: Use description field to provide details for decision-making
  4. Test with staging keys: Use test keys (coming soon) for development
  5. Monitor usage: Keep an eye on your API key usage in the dashboard

Need Help?