# 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! 🎉