n8n Integration Guide for Encore Health OS

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Table of Contents

1. Introduction & Overview
2. Architecture & Data Flow
3. n8n Setup Guide
4. Encore Health OS Configuration
5. Data Mapping Reference
6. Security Best Practices
7. Common Integration Patterns
8. Troubleshooting Guide
9. Advanced: MCP Integration

​

Introduction & Overview

​

Purpose

​

Hybrid Approach

• Encore Health OS (FW-03 Engine): Internal workflows, tenant-scoped automations, database operations
• n8n: External integrations, visual workflow design, complex branching logic, 400+ pre-built connectors

​

When to Use n8n

• ✅ External SaaS integrations (Salesforce, HubSpot, Slack, Google Workspace)
• ✅ Complex branching logic (if/else, switch, loops)
• ✅ Multi-step orchestration (approval chains, escalation workflows)
• ✅ Visual workflow design (drag-and-drop, no-code)
• ✅ Error handling & retries (advanced fault tolerance)
• ✅ Data transformation (JSON manipulation, aggregation)

​

When to Use Encore Health OS (FW-03)

• ✅ Tenant-scoped automations (org/site-specific rules)
• ✅ Database operations (create/update records with RLS)
• ✅ Internal notifications (via Platform Notifications)
• ✅ Simple webhooks (one-off API calls)
• ✅ Form validations (immediate feedback)

​

Architecture & Data Flow

​

High-Level Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        Encore Health OS Platform                          │
│                                                                     │
│  ┌──────────────┐     ┌─────────────────┐     ┌─────────────────┐ │
│  │ Form Submit  │────▶│ FW-03 Automation│────▶│ Call Webhook    │ │
│  │  (Trigger)   │     │ Rules Engine    │     │    Action       │ │
│  └──────────────┘     └─────────────────┘     └────────┬────────┘ │
│                                                         │          │
└─────────────────────────────────────────────────────────┼──────────┘
                                                          │
                                        HTTPS POST        │
                                        (JSON payload)    │
                                                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                            n8n Workflow                             │
│                                                                     │
│  ┌──────────────┐     ┌─────────────────┐     ┌─────────────────┐ │
│  │   Webhook    │────▶│  Process Data   │────▶│  External API   │ │
│  │   Trigger    │     │ (Transform/Map) │     │ (Slack, CRM...)  │ │
│  └──────────────┘     └─────────────────┘     └─────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

​

Data Format

{
  "trigger_type": "form_submission",
  "trigger_data": {
    "submission_id": "uuid",
    "form_id": "uuid",
    "form_name": "Employee Onboarding Form",
    "submission_data": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "start_date": "2025-12-01"
    },
    "submitted_by": "uuid",
    "submitted_at": "2025-11-25T10:30:00Z",
    "organization_id": "uuid",
    "site_id": "uuid"
  },
  "rule_id": "uuid",
  "rule_name": "New Hire Notification",
  "timestamp": "2025-11-25T10:30:05Z"
}

​

n8n Setup Guide

​

Step 1: Create a New Workflow

1. Log into your n8n instance
2. Click “New Workflow”
3. Give it a descriptive name (e.g., “Encore Health OS Form to Slack”)

​

Step 2: Add Webhook Trigger

1. Click “Add first step”
2. Search for “Webhook” and select it
3. Configure webhook settings:
   • HTTP Method: POST
   • Path: Leave default or customize (e.g., /encore-health-os/form-submission)
   • Authentication: Choose based on security needs (see Security)
   • Response Mode: Last Node (if n8n needs to return data)

​

Step 3: Get Webhook URL

1. Click “Listen for Test Event” or “Listen for Production Event”
2. Copy the webhook URL (e.g., https://your-n8n-instance.com/webhook/abc123)
3. Important: Use the Production URL for live automations

​

Step 4: Test Webhook

1. Keep n8n in “Listen” mode
2. Send a test POST request:
   curl -X POST https://your-n8n-instance.com/webhook/abc123 \
     -H "Content-Type: application/json" \
     -d '{"test": "data"}'
   
3. Verify n8n receives the payload

​

Step 5: Build Workflow Logic

1. Add “Slack” node
2. Select “Send Message” operation
3. Map webhook data:
   • Channel: #new-hires
   • Message:
     New employee starting: {{$json.trigger_data.submission_data.first_name}} {{$json.trigger_data.submission_data.last_name}}
     Start Date: {{$json.trigger_data.submission_data.start_date}}
     

​

Step 6: Activate Workflow

1. Click “Save” in the top right
2. Toggle “Active” to enable the workflow
3. The webhook is now live and ready to receive data from Encore Health OS

​

Encore Health OS Configuration

​

Step 1: Create Automation Rule

1. Navigate to Forms & Workflow → Automations
2. Click “Create Automation”
3. Configure trigger:
   • Trigger Type: Form Submission
   • Form: Select target form (e.g., “Employee Onboarding Form”)

​

Step 2: Add Conditions (Optional)

Field: "employment_type"
Operator: "equals"
Value: "Full-Time"

​

Step 3: Add “Call Webhook” Action

1. Click “Add Action”
2. Select “Call Webhook”
3. Configure webhook action:
   • URL: Paste your n8n webhook URL
   • Method: POST
   • Headers:
     {
       "Content-Type": "application/json",
       "Authorization": "Bearer YOUR_SECRET_TOKEN"
     }
     
   • Body Template: Use dynamic values (see Data Mapping)

​

Step 4: Configure Body Template

{
  "employee": {
    "first_name": "{{submission_data.first_name}}",
    "last_name": "{{submission_data.last_name}}",
    "email": "{{submission_data.email}}",
    "start_date": "{{submission_data.start_date}}"
  },
  "metadata": {
    "form_id": "{{form_id}}",
    "form_name": "{{form_name}}",
    "submitted_at": "{{submitted_at}}",
    "organization_id": "{{organization_id}}"
  }
}

​

Step 5: Test with Dry Run

1. Click “Test Automation”
2. Select “Dry Run” mode
3. Submit a test form or use sample data
4. Check n8n workflow execution logs
5. Verify data mapping is correct

​

Step 6: Activate Automation

1. Set Status: Active
2. Set Requires Approval: false (for trusted workflows)
3. Click “Save”

​

Data Mapping Reference

​

Available Trigger Data Fields

​

Dynamic Value Syntax

​

Simple Field Access

{
  "email": "{{submission_data.email}}",
  "phone": "{{submission_data.phone}}"
}

​

Nested Field Access

{
  "contact": {
    "first_name": "{{submission_data.contact.first_name}}",
    "last_name": "{{submission_data.contact.last_name}}"
  }
}

​

Metadata Fields

{
  "source": "Encore Health OS",
  "form_name": "{{form_name}}",
  "timestamp": "{{submitted_at}}"
}

​

Example Mappings

​

Slack Notification

{
  "channel": "#new-hires",
  "text": "New employee {{submission_data.first_name}} {{submission_data.last_name}} starting on {{submission_data.start_date}}",
  "metadata": {
    "form_id": "{{form_id}}",
    "submitted_at": "{{submitted_at}}"
  }
}

​

CRM Update (Salesforce, HubSpot)

{
  "contact": {
    "email": "{{submission_data.email}}",
    "firstName": "{{submission_data.first_name}}",
    "lastName": "{{submission_data.last_name}}",
    "phone": "{{submission_data.phone}}",
    "company": "{{organization_id}}",
    "properties": {
      "start_date": "{{submission_data.start_date}}",
      "employment_type": "{{submission_data.employment_type}}"
    }
  }
}

​

Google Sheets Row

{
  "values": [
    "{{submission_data.first_name}}",
    "{{submission_data.last_name}}",
    "{{submission_data.email}}",
    "{{submission_data.start_date}}",
    "{{submitted_at}}"
  ]
}

​

Security Best Practices

​

1. Always Use HTTPS

http://your-n8n-instance.com/webhook/abc123  # ❌ Insecure

https://your-n8n-instance.com/webhook/abc123  # ✅ Secure

​

2. Implement Authentication

​

Option A: Header Authentication (Recommended)

{
  "Authorization": "Bearer YOUR_SECRET_TOKEN"
}

• Webhook settings → Authentication → Header Auth
• Header Name: Authorization
• Header Value: Bearer YOUR_SECRET_TOKEN

​

Option B: Basic Authentication

{
  "Authorization": "Basic base64(username:password)"
}

​

Option C: Query Parameter (Less Secure)

https://your-n8n-instance.com/webhook/abc123?token=YOUR_SECRET

​

3. Protect Sensitive Data

• Never log PHI/PII in webhook bodies or n8n logs
• Use encrypted storage in n8n for credentials
• Implement field-level encryption for sensitive submission data

​

4. Rate Limiting & Circuit Breaker

• Circuit breaker: Trips after 5 consecutive failures
• Timeout: 30-second webhook timeout
• Retry logic: 3 retries with exponential backoff

• Rate limits on external APIs
• Error responses (return 4xx/5xx appropriately)

​

5. IP Whitelisting (Optional)

1. Get Encore Health OS’s outbound IP addresses
2. Configure firewall rules to allow only those IPs
3. Blocks unauthorized webhook calls

​

6. Audit Logging

• Enable automation logs in Encore Health OS (automatic)
• Enable execution logs in n8n
• Review logs regularly for anomalies

​

Common Integration Patterns

​

Pattern 1: Form → n8n → Slack Notification

1. Trigger: Form submission on “Contact Form”
2. Action: Call webhook to n8n

1. Webhook (receive form data)
2. Slack → Send message to #inquiries
   • Message: New inquiry from {{submission_data.name}} ({{submission_data.email}})

{
  "name": "{{submission_data.name}}",
  "email": "{{submission_data.email}}",
  "message": "{{submission_data.message}}"
}

​

Pattern 2: Form → n8n → Google Sheets

1. Trigger: Form submission on “Event Registration”
2. Action: Call webhook to n8n

1. Webhook (receive form data)
2. Google Sheets → Append row
   • Sheet ID: your-sheet-id
   • Values: [name, email, event_date, submitted_at]

{
  "name": "{{submission_data.name}}",
  "email": "{{submission_data.email}}",
  "event_date": "{{submission_data.event_date}}",
  "submitted_at": "{{submitted_at}}"
}

​

Pattern 3: Form → n8n → CRM Update (Salesforce/HubSpot)

1. Trigger: Form submission on “Lead Capture Form”
2. Action: Call webhook to n8n

1. Webhook (receive form data)
2. HubSpot → Create or Update Contact
   • Email: {{submission_data.email}}
   • First Name: {{submission_data.first_name}}
   • Last Name: {{submission_data.last_name}}
   • Properties: Map additional fields

{
  "contact": {
    "email": "{{submission_data.email}}",
    "first_name": "{{submission_data.first_name}}",
    "last_name": "{{submission_data.last_name}}",
    "company": "{{submission_data.company}}",
    "phone": "{{submission_data.phone}}"
  }
}

​

Pattern 4: Form → n8n → Multi-Step Approval

1. Trigger: Form submission on “Expense Request”
2. Condition: Amount > $1000
3. Action: Call webhook to n8n

1. Webhook (receive expense data)
2. Slack → Send approval request to manager
3. Wait for Webhook (manager response)
4. IF approved:
   • Email → Notify requester (approved)
   • Database → Update expense status
5. IF denied:
   • Email → Notify requester (denied with reason)

{
  "expense": {
    "amount": "{{submission_data.amount}}",
    "description": "{{submission_data.description}}",
    "category": "{{submission_data.category}}",
    "requested_by": "{{submitted_by}}",
    "submitted_at": "{{submitted_at}}"
  },
  "approver": "{{submission_data.manager_email}}"
}

​

Pattern 5: Scheduled Trigger → n8n → Report Generation

1. Trigger: Scheduled (every Monday at 9 AM)
2. Action: Call webhook to n8n

1. Webhook (receive trigger)
2. Encore Health OS API → Fetch compliance data (via custom function)
3. Google Sheets → Create new sheet with data
4. Email → Send report link to compliance team

​

Troubleshooting Guide

​

Issue 1: Webhook Not Triggering

1. Check Encore Health OS automation logs:
   • Navigate to Automations → [Your Rule] → Logs
   • Look for execution_status: "failed" or timeout errors
2. Verify webhook URL is correct (copy from n8n production URL)
3. Check n8n workflow is Active (not paused)
4. Test webhook manually:
   curl -X POST https://your-n8n-instance.com/webhook/abc123 \
     -H "Content-Type: application/json" \
     -d '{"test": "manual_trigger"}'
   

• ✅ Ensure URL uses HTTPS
• ✅ Check firewall rules allow outbound connections
• ✅ Verify n8n instance is reachable from Encore Health OS

​

Issue 2: Authentication Errors (401/403)

1. Check Encore Health OS automation logs for HTTP status code
2. Verify authentication headers match n8n webhook configuration
3. Test authentication with curl:
   curl -X POST https://your-n8n-instance.com/webhook/abc123 \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"test": "auth_test"}'
   

• ✅ Re-generate authentication token in n8n
• ✅ Update token in Encore Health OS webhook headers
• ✅ Check header name matches (e.g., Authorization vs X-API-Key)

​

Issue 3: Data Mapping Errors

1. Use Encore Health OS dry-run mode:
   • Test automation with sample data
   • Check execution logs for payload sent
2. Check n8n execution logs:
   • View received payload in webhook node output
   • Verify field paths match expected structure
3. Compare expected vs actual payload structure

• ✅ Use correct field paths: {{submission_data.field_name}}
• ✅ Check for nested fields: {{submission_data.nested.field}}
• ✅ Verify form field keys match (case-sensitive)

// Expected
{"email": "{{submission_data.email}}"}

// Actual (if null)
{"email": null}

// Fix: Check form field key
// Is it "email" or "Email" or "email_address"?

​

Issue 4: Timeout Errors

1. Check n8n execution time in workflow logs
2. Identify slow nodes (external API calls, large data processing)
3. Test n8n workflow execution time manually

• ✅ Optimize n8n workflow (reduce API calls, use caching)
• ✅ Increase timeout in Encore Health OS (30s default, max 60s)
• ✅ Split complex workflows into multiple steps

​

Issue 5: Circuit Breaker Tripped

1. Check automation status in Encore Health OS:
   • Look for circuit_breaker_tripped: true
   • Review consecutive_failures count
2. Check n8n error logs for failure reasons

• ✅ Fix underlying n8n workflow issue
• ✅ Reset circuit breaker in Encore Health OS:
  • Edit automation rule
  • Save (resets circuit breaker)
• ✅ Monitor for recurring failures

​

Debugging Checklist

• Webhook URL is correct and uses HTTPS
• n8n workflow is Active
• Authentication headers are correct
• Data mapping uses correct field paths
• n8n workflow completes within timeout (30s)
• Encore Health OS automation status is Active
• Circuit breaker is not tripped
• Firewall allows outbound HTTPS connections
• n8n instance is reachable from Encore Health OS

​

Advanced: MCP Integration

​

What is n8n MCP?

• Execute n8n workflows during app building
• Query workflow definitions for documentation
• Create bidirectional integrations (Encore Health OS ↔ n8n)

​

When to Use MCP vs Webhooks

​

Setting Up n8n MCP

1. Enable MCP access in n8n (Settings → MCP access)
2. Enable “Available in MCP” for each workflow (workflow settings)
3. Connect n8n MCP server in Encore Health OS (Project Settings → Integrations)

​

MCP Use Case: Bidirectional Workflow

1. Form submission triggers automation
2. Automation calls n8n webhook
3. n8n workflow processes data
4. n8n calls Encore Health OS Edge Function (via MCP) to update database

1. Webhook (receive form data)
2. External API (e.g., validate address via Google Maps)
3. HTTP Request → Encore Health OS Edge Function (update database with validated address)

• ✅ Complex external processing in n8n
• ✅ Database updates maintain RLS policies
• ✅ Full error handling and logging

​

Summary

​

Quick Start Checklist

1. ✅ Create webhook trigger in n8n
2. ✅ Copy production webhook URL
3. ✅ Create automation rule in Encore Health OS
4. ✅ Add “Call Webhook” action with URL and auth
5. ✅ Map trigger data using {{field}} syntax
6. ✅ Test with dry-run mode
7. ✅ Activate automation and n8n workflow
8. ✅ Monitor logs for successful executions

​

Best Practices

• ✅ Always use HTTPS webhooks
• ✅ Implement authentication (Bearer token recommended)
• ✅ Test with dry-run mode before activating
• ✅ Monitor automation and n8n execution logs
• ✅ Document complex workflows
• ✅ Use circuit breakers for fault tolerance
• ✅ Never log sensitive data (PHI/PII)

​

Resources

• FW-03 Automation Engine Spec
• Automation Security Guide
• Integration Documentation
• n8n Official Documentation