homelab-docs/N8N-INTEGRATIONS.md

n8n Homelab Integrations - Quick Start Guide

n8n is running on your homelab network (10.10.10.207) and can access all local services. This guide sets up useful automations.

---

Network Access Verified

n8n can connect to:

• ✅ Home Assistant (10.10.10.110:8123)
• ✅ Prometheus (10.10.10.206:9090)
• ✅ Grafana (10.10.10.206:3001)
• ✅ Syncthing (10.10.10.200:8384)
• ✅ PiHole (10.10.10.10)
• ✅ Gitea (10.10.10.220:3000)
• ✅ Proxmox (10.10.10.120:8006, 10.10.10.102:8006)
• ✅ TrueNAS (10.10.10.200)
• ✅ All external APIs (via internet)

---

Initial Setup (First-Time)

1. Open https://n8n.htsn.io
2. Complete the setup wizard:
   • Owner Email: hutson@htsn.io
   • Owner Name: Hutson
   • Password: (choose secure password)
3. Skip data sharing (optional)

---

Credentials to Add in n8n

Go to Settings → Credentials and add:

1. Home Assistant

Field	Value
Credential Type	Home Assistant API
Host	http://10.10.10.110:8123
Access Token	(get from Home Assistant)

Get Token: Home Assistant → Profile → Long-Lived Access Tokens → Create Token

---

2. Prometheus

Field	Value
Credential Type	HTTP Request (Generic)
URL	http://10.10.10.206:9090
Authentication	None

---

3. Grafana

Field	Value
Credential Type	Grafana API
URL	http://10.10.10.206:3001
API Key	(create in Grafana)

Get API Key: Grafana → Administration → Service Accounts → Create → Add Token

---

4. Syncthing

Field	Value
Credential Type	HTTP Request (Generic)
URL	http://10.10.10.200:8384
Header Name	X-API-Key
Header Value	VFJ7XZPJoWvkYj6fKzpQxc9u3XC8KUBs

---

5. Telegram Bot

Field	Value
Credential Type	Telegram API
Access Token	8450212653:AAHoVBlNUuA0vtrVPMNUfSgJh_gmFMxlrBg

Your Chat ID: 1004084736

---

6. Proxmox

Field	Value
Credential Type	HTTP Request (Generic)
URL	http://10.10.10.120:8006
Authentication	API Token
Token	(use monitoring@pve token if needed)

---

Starter Workflows

Workflow 1: Homelab Health Check (Every Hour)

Nodes:

1. Schedule Trigger (every hour)
2. HTTP Request → Prometheus query for down hosts
   • URL: http://10.10.10.206:9090/api/v1/query
   • Query param: query=up{job=~"node.*"} == 0
3. If → Check if any hosts are down
4. Telegram → Send alert if hosts down

PromQL Query:

up{job=~"node.*"} == 0

---

Workflow 2: Daily Backup Status

Nodes:

1. Schedule Trigger (8am daily)
2. HTTP Request → Query Syncthing sync status
   • URL: http://10.10.10.200:8384/rest/db/status?folder=backup
   • Header: X-API-Key: VFJ7XZPJoWvkYj6fKzpQxc9u3XC8KUBs
3. Function → Check if folder is syncing
4. Telegram → Send daily status report

---

Workflow 3: High CPU Alert

Nodes:

1. Schedule Trigger (every 5 minutes)
2. HTTP Request → Prometheus CPU query
   • URL: http://10.10.10.206:9090/api/v1/query
   • Query: 100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
3. If → CPU > 90%
4. Telegram → Send alert

---

Workflow 4: UPS Power Event

Webhook Trigger Setup:

1. Create webhook trigger in n8n
2. Get webhook URL: https://n8n.htsn.io/webhook/ups-alert
3. Configure NUT to call webhook on power events

Nodes:

1. Webhook Trigger → Receive UPS event
2. Switch → Route by event type (on battery, low battery, online)
3. Telegram → Send appropriate alert

---

Workflow 5: Gitea → Deploy on Push

Nodes:

1. Webhook Trigger → Gitea push event
2. If → Check if branch is main
3. SSH → Connect to target server
4. Execute Command → git pull && docker-compose up -d
5. Telegram → Notify deployment complete

---

Workflow 6: Syncthing Folder Behind Alert

Nodes:

1. Schedule Trigger (every 30 minutes)
2. HTTP Request → Get all folder statuses
   • URL: http://10.10.10.200:8384/rest/stats/folder
3. Function → Check if any folder has errors or is significantly behind
4. If → Errors found
5. Telegram → Alert with folder name and status

---

Workflow 7: Grafana Alert Forwarder

Purpose: Forward Grafana alerts to Telegram

Nodes:

1. Webhook Trigger → Grafana webhook
2. Function → Parse alert data
3. Telegram → Format and send alert

Grafana Setup:

• Contact Point → Add webhook: https://n8n.htsn.io/webhook/grafana-alerts

---

Workflow 8: Daily Homelab Summary

Nodes:

1. Schedule Trigger (9am daily)
2. Multiple HTTP Requests in parallel:
   • Prometheus: System uptime
   • Prometheus: Average CPU usage (24h)
   • Prometheus: Disk usage
   • Syncthing: Sync status (all folders)
   • PiHole: Queries blocked (24h)
3. Function → Format data as summary
4. Telegram → Send daily report

Example Output:

🏠 Homelab Daily Summary

✅ All systems operational
⏱️  Uptime: 14 days
📊 Avg CPU: 12%
💾 Disk: 45% used
🔄 Syncthing: All folders in sync
🛡️  PiHole: 2,341 queries blocked

Last updated: 2025-12-27 09:00

---

Workflow 9: VM State Change Monitor

Nodes:

1. Schedule Trigger (every 1 minute)
2. HTTP Request → Query Proxmox API for VM list
3. Function → Compare with previous state (use Set node)
4. If → VM state changed
5. Telegram → Notify VM started/stopped

---

Workflow 10: Internet Speed Test Alert

Nodes:

1. Schedule Trigger (every 6 hours)
2. HTTP Request → Prometheus speedtest exporter
3. If → Download speed < 500 Mbps
4. Telegram → Alert about slow internet

---

Advanced Integration Ideas

Home Assistant Automations

• Turn on lights when server room temperature > 80°F
• Trigger workflows from HA button press
• Send sensor data to external services

Proxmox Automation

• Auto-snapshot VMs before updates
• Clone VMs for testing
• Monitor resource usage and rebalance

Media Management

• Notify when new Plex content added
• Auto-organize downloads
• Send weekly watch statistics

Backup Monitoring

• Verify all Syncthing folders synced
• Alert on ZFS scrub errors
• Monitor snapshot ages

Security

• Alert on failed SSH attempts (from logs)
• Monitor SSL certificate expiration
• Track unusual network traffic patterns

---

n8n Best Practices

1. Error Handling: Always add error workflows to catch failures
2. Rate Limiting: Don't query APIs too frequently
3. Credentials: Never hardcode - always use credential store
4. Testing: Use manual trigger during development
5. Logging: Add Set nodes to track workflow state
6. Backups: Export workflows regularly (Settings → Export)

---

Useful PromQL Queries for n8n

CPU Usage:

100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

Memory Usage:

(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

Disk Usage:

(node_filesystem_size_bytes{mountpoint="/"} - node_filesystem_avail_bytes{mountpoint="/"}) / node_filesystem_size_bytes{mountpoint="/"} * 100

Hosts Down:

up{job=~"node.*"} == 0

Syncthing Disconnected:

up{job=~"syncthing.*"} == 0

---

Webhook URLs

After creating webhooks in n8n, you'll get URLs like:

• https://n8n.htsn.io/webhook/your-webhook-name

These can be called from:

• Grafana alerts
• Home Assistant automations
• Gitea webhooks
• Custom scripts
• UPS monitoring (NUT)

---

Testing Credentials

Test each credential after adding:

1. Create simple workflow with manual trigger
2. Add HTTP Request node with credential
3. Execute and check response
4. Verify data returned correctly

---

Troubleshooting

Can't reach local service:

• Verify service IP and port
• Check if service requires HTTPS
• Test with curl from docker-host2 first

Webhook not triggering:

• Check n8n is accessible: curl https://n8n.htsn.io/webhook/test
• Verify webhook URL in external service
• Check n8n execution logs

Workflow fails silently:

• Enable "Execute on Error" workflow
• Check workflow execution list
• Add Function nodes to log data

API authentication fails:

• Verify credential is saved
• Check API token hasn't expired
• Test with curl manually first

---

Next Steps

1. Add Credentials - Start with Telegram and Prometheus
2. Create Test Workflow - Simple hourly health check
3. Test Telegram - Verify messages arrive
4. Build Gradually - Add one workflow at a time
5. Export Backups - Save workflows regularly

---

Resources

• n8n Docs: https://docs.n8n.io
• Community Workflows: https://n8n.io/workflows
• Your n8n: https://n8n.htsn.io
• Your API Docs: N8N.md

Last Updated: 2025-12-27