n8n Setup Guide - Opsmatic

Overview

n8n is a powerful, open-source workflow automation platform that can be self-hosted or used via n8n Cloud. Opsmatic can monitor both deployment types, providing comprehensive analytics and performance insights for your n8n workflows.

Prerequisites

Before connecting n8n to Opsmatic, ensure you have:

n8n Instance

Either self-hosted n8n or n8n Cloud account with admin access

API Access

Ability to create API keys in your n8n instance

Supported n8n Versions

Opsmatic supports:

n8n Cloud: All current versions
Self-hosted n8n: Version 0.190.0 and newer
Docker deployments: All supported n8n Docker images
Kubernetes deployments: Compatible with n8n Helm charts

Creating an n8n API Key

For n8n Cloud

Access Settings

Log into your n8n Cloud instance and click on Settings in the left sidebar

Navigate to API Keys

Click on “API Keys” in the settings menu

Create New Key

Click “Create API Key” button

Configure Key

Name: Enter “Opsmatic Monitoring” or similar
Permissions: Select appropriate permissions (see below)
Expiration: Set to “Never” or long-term date

Copy Key

Copy the generated API key immediately (it won’t be shown again)

For Self-Hosted n8n

Access Admin Panel

Navigate to your n8n instance URL and log in as an admin user

Open Settings

Click the Settings gear icon in the left sidebar

Navigate to API Keys

Select “API Keys” from the settings menu

Generate Key

Click “Create API Key” and configure:

Label: “Opsmatic Integration”
Permissions: Read access to workflows and executions

Save Key

Copy the API key to a secure location

Required API Permissions

For optimal monitoring, your n8n API key should have these permissions:

Essential Permissions (Required)

Workflow Read: View workflow definitions and metadata
Execution Read: Access execution logs and history
Instance Read: Get basic instance information

Recommended Permissions

Workflow List: Enumerate all available workflows
User Read: Access user information for execution context
Credential Read: Limited credential metadata (not values)

Optional Permissions

Settings Read: Instance configuration for advanced analytics
Tags Read: Workflow categorization and organization

Security Note: Only grant the minimum permissions necessary. Opsmatic never needs write access to your workflows or credentials.

Adding n8n Connection in Opsmatic

Step-by-Step Setup

Navigate to Connections

In Opsmatic, go to Connections from the sidebar menu

Add New Connection

Click “Add Connection” button

Select n8n

Choose n8n from the platform options

Enter Connection Details

Fill in the required information:

Basic Information

Service Name: Descriptive name (e.g., “Production n8n Server”)
Organization: Choose personal or organization context

Connection Settings

Base URL: Your n8n instance URL
API Key: The API key you created earlier

Test Connection

Click “Test Connection” to verify the setup

Save Connection

If the test succeeds, click “Save Connection”

Connection Configuration Details

n8n Cloud
Self-Hosted

Base URL Format:

https://[your-subdomain].app.n8n.cloud

Example:

https://mycompany.app.n8n.cloud

API Key Format:

Starts with n8n_api_
Followed by random characters
Example: n8n_api_abc123def456ghi789

Base URL Examples:

https://n8n.mycompany.com
https://automation.example.org
http://localhost:5678 (development only)

Docker Setup: If using Docker, ensure:

n8n is accessible on the specified port
SSL certificate is properly configured
API endpoints are enabled

Firewall Considerations:

Allow HTTPS (443) or HTTP (custom port) traffic
Ensure Opsmatic can reach your n8n instance
Consider IP allowlisting if needed

Verifying the Connection

Connection Test Results

When you test your n8n connection, you should see:

Successful Connection

✅ API authentication successful
✅ Workflow count retrieved
✅ Instance version detected
✅ Response time measured

Connection Information

n8n version number
Number of accessible workflows
Response time in milliseconds
Instance type (cloud/self-hosted)

Troubleshooting Connection Issues

Authentication Failed

Error: “Invalid API key” or 401 UnauthorizedSolutions:

Verify API key is copied correctly (no extra spaces)
Check if API key has expired
Ensure API key has proper permissions
Re-generate API key if necessary

Cannot Reach Server

Error: “Connection timeout” or “Server not found”Solutions:

Verify Base URL is correct and accessible
Check if n8n instance is running
Test URL in browser to confirm accessibility
Check firewall and network settings

Permission Denied

Error: “Access denied” or 403 ForbiddenSolutions:

Review API key permissions
Ensure user account has admin access
Check if API access is enabled in n8n settings
Verify organization/team permissions

SSL/TLS Issues

Error: “Certificate error” or “SSL handshake failed”Solutions:

Ensure valid SSL certificate on n8n instance
Check certificate expiration
For self-signed certificates, contact support
Verify HTTPS configuration

What Data is Monitored

Once connected, Opsmatic will monitor:

Workflow Information

Workflow Metadata

Workflow names and unique identifiers
Creation and modification timestamps
Active/inactive status
Workflow complexity (node count)
Tags and categories

Execution Data

Execution start and end times
Success/failure status
Execution duration
Error details and stack traces
Data processed (size and volume)

Performance Metrics

Average execution time per workflow
Success rate over time
Resource usage patterns
Peak execution periods
Error frequency and types

Instance Health

Availability Monitoring

API response time tracking
Uptime/downtime detection
Connection stability metrics
Service availability percentage

Performance Tracking

Request/response latency
API endpoint responsiveness
Data synchronization success
System load indicators

Advanced Configuration

Custom Sync Settings

For high-volume n8n instances, you can configure:

Sync Frequency
Data Filters
Rate Limiting

Default: Every 15 minutes Options:

Every 5 minutes (high activity)
Every 30 minutes (standard)
Hourly (low activity)
Custom intervals

Webhook Integration (Advanced)

For real-time monitoring, set up webhooks:

Webhook integration requires additional setup and is recommended for advanced users only.

Enable Webhooks in n8n

Configure webhook endpoints in your n8n instance settings

Configure Opsmatic Webhook URL

Use the webhook URL provided in your connection settings

Set Trigger Events

Configure webhooks to trigger on:

Workflow execution start/end
Execution failures
System events

Test Webhook Delivery

Verify webhook payloads are received correctly

Security Best Practices

API Key Management

Create dedicated API keys for Opsmatic
Use descriptive names for easy identification
Regularly rotate API keys
Never share keys or commit them to version control

Network Security

Use HTTPS for all connections
Implement IP allowlisting if possible
Monitor API key usage and access
Set appropriate permissions (read-only)

Monitoring Multiple n8n Instances

If you have multiple n8n deployments:

Organization Strategy

Environment Separation

Create separate connections for:

Production: Production n8n - Main
Staging: Staging n8n - Testing
Development: Dev n8n - Local

Geographic Distribution

For global deployments:

US East: n8n US-East Production
Europe: n8n EU Production
Asia Pacific: n8n APAC Production

Client/Project Separation

For agencies or multiple projects:

Client A: Client A - Production n8n
Project X: Project X - Automation Hub
Internal: Internal Tools - n8n

What’s Next?

After successfully connecting your n8n instance:

Test Your Connection

Learn how to properly test and validate your n8n connection

View Analytics

Start monitoring your n8n workflow performance and analytics

Set up Make.com

Add Make.com connections for comprehensive automation monitoring

Dashboard Overview

Explore your monitoring dashboard with n8n data

Getting started

Authentication

Connections

Organizations

Dashboard

Analytics

Billing

API Documentation

Support

​Overview

​Prerequisites

n8n Instance

API Access

​Supported n8n Versions

​Creating an n8n API Key

​For n8n Cloud

​For Self-Hosted n8n

​Required API Permissions

​Adding n8n Connection in Opsmatic

​Step-by-Step Setup

​Connection Configuration Details

​Verifying the Connection

​Connection Test Results

Successful Connection

Connection Information

​Troubleshooting Connection Issues

​What Data is Monitored

​Workflow Information

​Instance Health

​Advanced Configuration

​Custom Sync Settings

​Webhook Integration (Advanced)

​Security Best Practices

API Key Management

Network Security

​Monitoring Multiple n8n Instances

​Organization Strategy

​What’s Next?

Test Your Connection

View Analytics

Set up Make.com

Dashboard Overview

Overview

Prerequisites

Supported n8n Versions

Creating an n8n API Key

For n8n Cloud

For Self-Hosted n8n

Required API Permissions

Adding n8n Connection in Opsmatic

Step-by-Step Setup

Connection Configuration Details

Verifying the Connection

Connection Test Results

Troubleshooting Connection Issues

What Data is Monitored

Workflow Information

Instance Health

Advanced Configuration

Custom Sync Settings

Webhook Integration (Advanced)

Security Best Practices

Monitoring Multiple n8n Instances

Organization Strategy

What’s Next?