Skip to main content

​
n8n Integration

Integrate HITL.sh with n8n to create powerful automated workflows that seamlessly incorporate human decision-making. Perfect for content moderation, approval workflows, and quality assurance processes.
Before configuring n8n, install the HITL.sh mobile app (App Store | Google Play) since it’s an integral part of the setup.
n8n workflow with HITL.sh integration

​
Why Use n8n with HITL.sh?

Visual Workflow Builder

Design complex automation workflows with an intuitive drag-and-drop interface

300+ Integrations

Connect HITL.sh with popular services like Slack, Gmail, databases, and more

Self-Hosted Option

Deploy on your own infrastructure for complete data control and privacy

Open Source

Fully transparent codebase you can customize and extend to your needs

​
Installation Methods

n8n offers two ways to add HITL.sh integration to your workflows:

​
Setting Up Credentials

Configure your HITL.sh API credentials in n8n:
1

Get Your API Key

  1. Log in to your HITL.sh dashboard at my.hitl.sh
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy your API key (keep it secure!)
2

Add Credentials in n8n

  1. In n8n, go to Credentials → New
  2. Search for “HITL.sh”
  3. Paste your API key
Setting up HITL.sh API credentials in n8n
3

Test Connection

Click Test Credentials to verify the connection

​
Available Response Types

HITL.sh n8n nodes support six different response types for collecting structured feedback from reviewers:
Free-form text input with character limits:
{
  "response_type": "text",
  "response_config": {
    "placeholder": "Enter your feedback...",
    "min_length": 10,
    "max_length": 500,
    "required": true
  }
}
Response format: "response_data": "The content looks good but needs minor edits..."
Choose one option from a predefined list:
{
  "response_type": "single_select",
  "response_config": {
    "options": ["Approve", "Reject", "Needs Review"]
  }
}
Response format: "response_data": "approve"
Choose multiple options from a list:
{
  "response_type": "multi_select",
  "response_config": {
    "options": ["Grammar Issues", "Factual Errors", "Tone Problems"],
    "max_selections": 3
  }
}
Response format: "response_data": ["grammar_issues", "tone_problems"]
Numeric rating on a custom scale:
{
  "response_type": "rating",
  "response_config": {
    "scale_min": 1,
    "scale_max": 10,
    "scale_step": 0.5
  }
}
Response format: "response_data": 7.5
Numeric input with validation:
{
  "response_type": "number",
  "response_config": {
    "min_value": 0,
    "max_value": 1000,
    "decimal_places": 2
  }
}
Response format: "response_data": 299.99
Simple yes/no decisions:
{
  "response_type": "boolean",
  "response_config": {
    "true_label": "Approved",
    "false_label": "Rejected"
  }
}
Response format: "response_data": true

​
Configuring the HITL.sh Node

Add the HITL.sh node to your workflow and configure it:
Configuring HITL.sh node parameters in n8n

​
Required Parameters

​
Loop ID
string
required
The unique identifier of your HITL loop where reviewers will process the request
​
Request Text
string
required
The content or question you want reviewers to evaluate
​
Response Type
select
required
Choose from: text, single_select, multi_select, rating, number, boolean
​
Response Config
object
required
Configuration object specific to your chosen response type

​
Optional Parameters

​
Processing Type
select
default:"time-sensitive"
time-sensitive or deferred - determines urgency of the request
​
Priority
select
default:"medium"
low, medium, high, or critical - affects reviewer notification
​
Timeout Seconds
number
Time limit before default response is used (60-86400 seconds)
​
Default Response
varies
Fallback value if request times out (format matches response type)
​
Context
object
Additional metadata to help reviewers make informed decisions

​
Response Data Structure

When a reviewer completes a request, you’ll receive comprehensive response data:
Complete response data structure from HITL.sh in n8n
{
  "request_id": "65f1234567890abcdef12348",
  "loop_id": "65f1234567890abcdef12345",
  "status": "completed",
  "priority": "high",
  "response_data": "approve",
  "response_by_user": {
    "id": "65f1234567890abcdef12350",
    "name": "John Reviewer",
    "email": "[email protected]"
  },
  "response_time_seconds": 145.5,
  "context": {
    "user_id": "user_123",
    "post_id": "post_456"
  },
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:32:25Z"
}

​
Example Workflow: Customer Refund Approval

Here’s a complete workflow that automatically processes refund requests with human oversight:
n8n workflow for customer refund approvals with HITL.sh

​
Workflow Steps

1

Trigger: New Refund Request

Webhook or form submission triggers when customer requests refund
2

Check Refund Amount

Conditional node routes based on refund amount:
  • Under $50: Auto-approve
  • 50−50-500: Standard review
  • Over $500: Priority review
3

HITL.sh Review Node

Send to human reviewer with refund details and customer history
{
  "loop_id": "refund_approvals",
  "request_text": "Customer requesting ${{ $json.amount }} refund\nReason: {{ $json.reason }}\nCustomer lifetime value: ${{ $json.customer_ltv }}",
  "response_type": "single_select",
  "response_config": {
    "options": ["Approve Full", "Approve Partial", "Deny", "Escalate"]
  },
  "priority": "{{ $json.amount > 500 ? 'high' : 'medium' }}",
  "context": {
    "customer_id": "{{ $json.customer_id }}",
    "order_id": "{{ $json.order_id }}",
    "amount": "{{ $json.amount }}"
  }
}
4

Process Decision

Switch node routes based on human decision
5

Execute Action

  • Approved: Process refund and send confirmation
  • Denied: Send explanation email
  • Escalate: Notify management team
6

Update Records

Log decision in CRM/database for audit trail

​
Best Practices

Clear Instructions

Provide reviewers with all context needed to make informed decisions

Appropriate Timeouts

Set realistic timeouts based on request urgency and reviewer availability

Safe Defaults

Always specify conservative default responses for timeout scenarios

Error Handling

Add error nodes to handle API failures gracefully

​
Troubleshooting

Solution:
  • Verify installation completed successfully
  • Restart n8n instance
  • Check n8n logs for installation errors
Solution:
  • Verify API key is correct
  • Check API key has required permissions
  • Ensure API key hasn’t expired
Solution:
  • Increase timeout_seconds parameter
  • Verify loop has active reviewers
  • Check reviewer notification settings

​
Next Steps

Zapier Integration

Learn about our Zapier integration for simpler automation

Make Integration

Explore Make.com integration with webhook triggers

API Reference

View complete API documentation for custom integrations

Community Support

Join our Discord community for help and examples