fred/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0f51041a04c06b7079e0b9f94345005cbb1c4ce0
homelab-docs/N8N-UPTIME-KUMA-GUIDE.md

8.8 KiB
Raw Blame History

n8n + Uptime Kuma Integration Guide

n8n for Beginners: This guide will walk you through setting up smart notifications for your infrastructure monitoring.

What This Does

This n8n workflow receives alerts from Uptime Kuma and routes them intelligently:

  • CRITICAL alerts → Email + Discord/Slack (immediate)
  • PUBLIC alerts → Discord (after retry threshold)
  • INTERNAL/METRICS/UTILITY → Logged only (no spam)

All alerts are logged for debugging and historical tracking.

Step 1: Import Workflow into n8n

1.1 Access n8n

Go to http://10.0.10.22:5678

1.2 Import the Workflow

  1. Click Workflows (left sidebar)
  2. Click Add Workflow (top right)
  3. Click the ⋮ menu (top right) → Import from File
  4. Select: C:\Users\Fred\projects\n8n-uptime-kuma-workflow.json
  5. Click Import

1.3 Activate the Workflow

  1. The workflow editor will open
  2. Toggle the Active switch (top right) to ON
  3. You should see "Workflow activated" message

Step 2: Get Your Webhook URL

2.1 Find the Webhook URL

  1. In the workflow editor, click on the "Webhook - Uptime Kuma" node (first blue node)
  2. Look for Test URL or Production URL
  3. Copy the production URL - it should look like: 
    http://10.0.10.22:5678/webhook/uptime-kuma

Save this URL - you'll need it for Uptime Kuma!

Step 3: Configure Uptime Kuma Notifications

3.1 Create n8n Notification Channel

  1. Go to Uptime Kuma: http://10.0.10.26:3001
  2. Click Settings (left sidebar)
  3. Click Notifications tab
  4. Click Add New Notification

3.2 Configure Webhook

  • Notification Type: Select Webhook
  • Friendly Name: n8n Alert Router
  • POST URL: http://10.0.10.22:5678/webhook/uptime-kuma
  • Content Type: application/json
  • Notification Sound: (your preference)
  • Click Test to verify
  • Click Save

3.3 Assign to Monitors

Now assign this notification to your monitors:

  1. Go to Dashboard
  2. Click on a CRITICAL monitor (e.g., "Proxmox - main-pve")
  3. Click Edit
  4. Scroll to Notifications
  5. Select n8n Alert Router
  6. Apply on: Select When status is DOWN
  7. Click Save

Repeat for all CRITICAL monitors (you can select multiple monitors and edit in bulk)

Step 4: Enable Notification Channels

By default, all notification nodes are disabled (to prevent errors). Enable the ones you want to use:

Option A: Discord (Recommended for Beginners)

4.1 Create Discord Webhook:

  1. Open Discord
  2. Go to your server → Settings → Integrations
  3. Click Webhooks → New Webhook
  4. Name it "Uptime Kuma Alerts"
  5. Select channel (e.g., #monitoring)
  6. Copy the Webhook URL

4.2 Configure in n8n:

  1. In the workflow, click "Discord - CRITICAL Alert" node
  2. Click Parameters
  3. Paste your Discord webhook URL
  4. Toggle the node Enabled (remove checkmark from "Disabled")
  5. Click Save (top right)

Repeat for "Discord - PUBLIC Alert" if you want public service alerts too.

Option B: Email (SMTP)

4.1 Configure in n8n:

  1. Click "Email - CRITICAL Alert" node
  2. Click Credentials → Create New
  3. Choose your email provider:
    • Gmail: Use App Password (not your main password)
    • Outlook/Office365: Use SMTP settings
    • Custom SMTP: Enter your SMTP details

Example: Gmail Setup

  1. Click Test to verify
  2. Click Save
  3. Enable the node (uncheck "Disabled")

Option C: Slack

4.1 Create Slack App:

  1. Go to https://api.slack.com/apps
  2. Click Create New App → From scratch
  3. Name: "Uptime Kuma"
  4. Select your workspace
  5. Go to OAuth & Permissions
  6. Add Bot Token Scopes: chat:write, chat:write.public
  7. Click Install to Workspace
  8. Copy the Bot User OAuth Token

4.2 Configure in n8n:

  1. Click "Slack - CRITICAL Alert" node
  2. Click Credentials → Create New
  3. Paste your Bot Token
  4. Click Save
  5. Enable the node

Step 5: Test Your Setup

5.1 Trigger a Test Alert

Let's test with a non-critical monitor:

  1. Go to Uptime Kuma
  2. Find "[UTILITY] CA Server" monitor
  3. Click Edit
  4. Temporarily change port from 8443 to 9999 (invalid port)
  5. Click Save
  6. Wait 30-60 seconds for the monitor to check

5.2 Check n8n Execution

  1. Go to n8n: http://10.0.10.22:5678
  2. Click Executions (left sidebar)
  3. You should see a new execution
  4. Click it to view details

5.3 Verify Alert Received

  • Discord: Check your #monitoring channel
  • Email: Check your inbox
  • Slack: Check your channel

5.4 Fix the Monitor

  1. Go back to Uptime Kuma
  2. Edit the CA Server monitor
  3. Change port back to 8443
  4. Save

Workflow Overview

Here's what happens when a monitor goes down:

Uptime Kuma Alert
       ↓
   n8n Webhook Receives
       ↓
   Format Alert Data
   (Parses monitor info, status, error)
       ↓
   ┌──────────────┬──────────────┐
   ↓              ↓              ↓
Is CRITICAL?  Is PUBLIC?    Log All
   ↓              ↓           Alerts
   ↓              ↓
Email +      Discord
Discord +    (Optional)
Slack
(Optional)

Smart Routing:

  • CRITICAL monitors (VPS, Proxmox, PostgreSQL) → Immediate multi-channel alerts
  • PUBLIC monitors (websites) → Discord only
  • Everything else → Logged for review

Customization Ideas

Add SMS Alerts (via Twilio)

  1. Add Twilio node after "Is CRITICAL?"
  2. Configure with your Twilio account
  3. Send SMS for CRITICAL alerts only

Add Phone Call Alerts

  1. Use Twilio or VoIP.ms node
  2. Trigger phone calls for critical infrastructure failures
  3. Only for CRITICAL monitors to avoid spam

Create Alert Batching

  1. Add Wait node before Discord/Email
  2. Collect multiple alerts for 5 minutes
  3. Send one consolidated message

Add Status Page Integration

  1. After "Format Alert Data", add HTTP Request node
  2. POST to your status page API
  3. Auto-update public status page

Store Alerts in Database

  1. Add PostgreSQL node (connect to 10.0.10.20)
  2. Create alerts table
  3. Log all alerts for historical analysis

Troubleshooting

Webhook Not Receiving Data

  • Check workflow is Active (toggle at top right)
  • Verify webhook URL is correct in Uptime Kuma
  • Check n8n executions for errors

Discord/Email Not Sending

  • Make sure node is Enabled (not grayed out)
  • Check credentials are configured
  • Look at n8n execution details for error messages

Too Many Alerts

  • Increase retry counts in Uptime Kuma monitors
  • Change "Apply on" to only DOWN (not also UP)
  • Add filtering logic in n8n (only alert after X failures)

Not Enough Alerts

  • Check monitor has notification assigned
  • Verify "Apply on" includes DOWN status
  • Check n8n workflow is active

Advanced: Alert Suppression (Prevent Spam)

Add this after "Format Alert Data" to suppress duplicate alerts:

  1. Add Function node
  2. Code:
// Suppress duplicate alerts within 15 minutes
const alertKey = `${$json.fullName}-${$json.status}`;
const lastAlert = $workflow.staticData[alertKey] || 0;
const now = Date.now();

if (now - lastAlert < 15 * 60 * 1000) {
  // Alert sent less than 15 min ago - suppress
  return [];
}

// Send alert and remember timestamp
$workflow.staticData[alertKey] = now;
return [$input.item];

This prevents getting the same alert repeatedly.

Next Steps

  1. ✅ Import workflow into n8n
  2. ✅ Activate workflow and get webhook URL
  3. ✅ Configure Uptime Kuma notification
  4. ✅ Enable Discord/Email/Slack notifications
  5. ✅ Test with a non-critical monitor
  6. ✅ Assign notifications to all CRITICAL monitors
  7. ⏸️ Customize alert routing (optional)
  8. ⏸️ Add SMS/phone call alerts (optional)
  9. ⏸️ Create alert dashboard in Grafana (optional)

n8n Dashboard: http://10.0.10.22:5678 Uptime Kuma: http://10.0.10.26:3001 Workflow File: C:\Users\Fred\projects\n8n-uptime-kuma-workflow.json

Pro Tip: Once you're comfortable with n8n, you can create workflows for:

  • Auto-restarting failed services
  • Creating GitHub issues when monitors fail
  • Sending daily/weekly uptime reports
  • Integration with your homelab automation

Welcome to n8n! 🎉

Reference in New Issue View Git Blame Copy Permalink