318 lines
8.8 KiB
Markdown
318 lines
8.8 KiB
Markdown
# 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**
|
|
- **From Email:** your-gmail@gmail.com
|
|
- **To Email:** your-alert-email@gmail.com
|
|
- **SMTP Host:** smtp.gmail.com
|
|
- **SMTP Port:** 587
|
|
- **Username:** your-gmail@gmail.com
|
|
- **Password:** (App Password from Google Account settings)
|
|
- **Secure:** TLS
|
|
|
|
4. Click **Test** to verify
|
|
5. Click **Save**
|
|
6. 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:
|
|
```javascript
|
|
// 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! 🎉
|