Add webhook notification provider

Author: zigazajc007

README.md

@@ -7,7 +7,7 @@ A high-performance uptime monitoring system built with Bun and ClickHouse. Recei
 - **Pulse-Based Monitoring** - Services send heartbeats; missing pulses trigger alerts
 - **Hierarchical Groups** - Organize monitors with flexible health strategies (any-up, all-up, percentage)
 - **Custom Metrics** - Track up to 3 numeric values per monitor (player count, connections, etc.)
-- **Multi-Channel Notifications** - Discord, Email, Ntfy and Telegram support with per-monitor control
+- **Multi-Channel Notifications** - Discord, Email, Ntfy, Telegram and Webhook support with per-monitor control
 - **Dependency-Based Notification Suppression** - Define dependencies between monitors/groups to avoid notification storms when infrastructure fails
 - **Real-Time Status Pages** - WebSocket-powered live updates
 - **Self-Healing** - Automatic backfill when the monitor itself recovers from downtime
@@ -78,18 +78,18 @@ curl http://localhost:3000/v1/status/:slug
 
 ## Documentation
 
-| Document                                                               | Description                                       |
-| ---------------------------------------------------------------------- | ------------------------------------------------- |
-| [Pulses](docs/pulses.md)                                               | How pulses work, timing, and best practices       |
-| [Configuration Guide](docs/configuration.md)                           | Complete config.toml reference                    |
-| [API Reference](docs/api.md)                                           | All endpoints and WebSocket events                |
-| [Admin API Reference](docs/admin-api.md)                               | CRUD endpoints for managing configuration via API |
-| [Notifications](docs/notifications.md)                                 | Setting up Discord, Email, Ntfy, Telegram         |
-| [Groups & Strategies](docs/groups.md)                                  | Organizing monitors hierarchically                |
-| [Dependencies](docs/dependencies.md)                                   | Notification suppression via dependencies         |
-| [Custom Metrics](docs/custom-metrics.md)                               | Tracking additional data points                   |
-| [PulseMonitor Integration](docs/pulsemonitor.md)                       | Automated monitoring from multiple regions        |
-| [Visual Configuration Editor](https://uptime-monitor.org/configurator) | Web-based UI for configuring monitors             |
+| Document                                                               | Description                                        |
+| ---------------------------------------------------------------------- | -------------------------------------------------- |
+| [Pulses](docs/pulses.md)                                               | How pulses work, timing, and best practices        |
+| [Configuration Guide](docs/configuration.md)                           | Complete config.toml reference                     |
+| [API Reference](docs/api.md)                                           | All endpoints and WebSocket events                 |
+| [Admin API Reference](docs/admin-api.md)                               | CRUD endpoints for managing configuration via API  |
+| [Notifications](docs/notifications.md)                                 | Setting up Discord, Email, Ntfy, Telegram, Webhook |
+| [Groups & Strategies](docs/groups.md)                                  | Organizing monitors hierarchically                 |
+| [Dependencies](docs/dependencies.md)                                   | Notification suppression via dependencies          |
+| [Custom Metrics](docs/custom-metrics.md)                               | Tracking additional data points                    |
+| [PulseMonitor Integration](docs/pulsemonitor.md)                       | Automated monitoring from multiple regions         |
+| [Visual Configuration Editor](https://uptime-monitor.org/configurator) | Web-based UI for configuring monitors              |
 
 ## Related Projects
 

bun.lock

@@ -294,4 +294,13 @@ chatId = "-1001234567890"
 # Optional: send to a specific forum topic
 # topicId = 123
 # Optional: send silently
-# disableNotification = false
+# disableNotification = false
+
+# Webhook configuration for critical alerts
+[notifications.channels.critical.webhook]
+enabled = false
+url = "https://example.com/webhook"
+# Optional: Custom headers for authentication
+#[notifications.channels.critical.webhook.headers]
+#Authorization = "Bearer your-token"
+#X-Api-Key = "your-api-key"

config.example.toml

@@ -596,6 +596,7 @@ curl -X POST -H "Authorization: Bearer <token>" \
 | `email`       | object | Email/SMTP configuration      |
 | `ntfy`        | object | Ntfy push notification config |
 | `telegram`    | object | Telegram bot configuration    |
+| `webhook`     | object | Webhook configuration         |
 
 **Discord configuration:**
 
@@ -653,6 +654,18 @@ curl -X POST -H "Authorization: Bearer <token>" \
 }
 ```
 
+**Webhook configuration:**
+
+```json
+{
+	"enabled": true,
+	"url": "https://example.com/webhook",
+	"headers": {
+		"Authorization": "Bearer your-token"
+	}
+}
+```
+
 **Success Response (201):**
 
 ```json

docs/admin-api.md

@@ -224,6 +224,74 @@ chatId = "-1001234567890"
 topicId = 42
 ```
 
+## Webhook
+
+Send notifications to any HTTP endpoint as a JSON POST request.
+
+```toml
+[notifications.channels.critical.webhook]
+enabled = true
+url = "https://example.com/webhook"
+
+[notifications.channels.critical.webhook.headers]
+Authorization = "Bearer your-token"
+```
+
+| Field     | Required | Description                         |
+| --------- | -------- | ----------------------------------- |
+| `enabled` | Yes      | Enable webhook notifications        |
+| `url`     | Yes      | Target URL to POST notifications to |
+| `headers` | No       | Custom HTTP headers (e.g. for auth) |
+
+### Payload Format
+
+All webhook notifications are sent as `POST` requests with `Content-Type: application/json`. The payload has a fixed structure:
+
+```json
+{
+	"type": "down",
+	"monitorId": "api-prod",
+	"monitorName": "Production API",
+	"sourceType": "monitor",
+	"timestamp": "2025-01-15T10:30:00.000Z",
+	"formattedTime": "2025-01-15 10:30:00",
+	"interval": 60,
+	"downtime": 120000,
+	"downtimeDuration": "2m 0s",
+	"consecutiveDownCount": 2
+}
+```
+
+| Field                          | Type   | Always Present | Description                                          |
+| ------------------------------ | ------ | -------------- | ---------------------------------------------------- |
+| `type`                         | string | Yes            | `down`, `still-down`, or `recovered`                 |
+| `monitorId`                    | string | Yes            | Monitor or group ID                                  |
+| `monitorName`                  | string | Yes            | Monitor or group display name                        |
+| `sourceType`                   | string | Yes            | `monitor` or `group`                                 |
+| `timestamp`                    | string | Yes            | ISO 8601 timestamp                                   |
+| `formattedTime`                | string | Yes            | Human-readable local time                            |
+| `interval`                     | number | Yes            | Check interval in seconds                            |
+| `downtime`                     | number | No             | Downtime duration in milliseconds                    |
+| `downtimeDuration`             | string | No             | Human-readable downtime (e.g. "2m 30s")              |
+| `consecutiveDownCount`         | number | No             | Number of consecutive down checks                    |
+| `previousConsecutiveDownCount` | number | No             | Previous consecutive down count                      |
+| `groupInfo`                    | object | No             | Present only for groups (strategy, childrenUp, etc.) |
+
+### Group Info Object
+
+When `sourceType` is `group`, the payload includes:
+
+```json
+{
+	"groupInfo": {
+		"strategy": "percentage",
+		"childrenUp": 2,
+		"totalChildren": 5,
+		"upPercentage": 40
+	}
+}
+```
+
 ## Assigning Channels to Monitors
 
 ```toml

docs/notifications.md

@@ -1,15 +1,15 @@
 {
 	"name": "uptimemonitor-server",
 	"module": "src/index.ts",
-	"version": "0.2.20",
+	"version": "0.2.21",
 	"type": "module",
 	"private": true,
 	"scripts": {
 		"start": "bun src/index.ts"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.9",
-		"@types/nodemailer": "^7.0.9"
+		"@types/nodemailer": "^7.0.10"
 	},
 	"peerDependencies": {
 		"typescript": "^5.9.3"

package.json

@@ -132,6 +132,7 @@ function serialize(input: any): Record<string, unknown> {
 	if (input.email) r.email = input.email;
 	if (input.ntfy) r.ntfy = input.ntfy;
 	if (input.telegram) r.telegram = input.telegram;
+	if (input.webhook) r.webhook = input.webhook;
 	return r;
 }
 
@@ -211,5 +212,22 @@ function validate(input: any, isUpdate: boolean): string[] {
 		}
 	}
 
+	// Webhook
+	if (input.webhook !== undefined && input.webhook !== null) {
+		if (typeof input.webhook !== "object" || Array.isArray(input.webhook)) {
+			e.push("webhook must be an object");
+		} else {
+			if (typeof input.webhook.enabled !== "boolean") e.push("webhook.enabled must be a boolean");
+			if (input.webhook.enabled) {
+				if (!input.webhook.url || typeof input.webhook.url !== "string") e.push("webhook.url is required when enabled");
+				if (input.webhook.headers !== undefined) {
+					if (typeof input.webhook.headers !== "object" || Array.isArray(input.webhook.headers)) {
+						e.push("webhook.headers must be an object");
+					}
+				}
+			}
+		}
+	}
+
 	return e;
 }

src/admin/notifications.ts

@@ -1239,6 +1239,48 @@ function validateTelegramConfig(config: unknown, channelId: string): any {
 	return result;
 }
 
+function validateWebhookConfig(config: unknown, channelId: string): any {
+	const errors: string[] = [];
+	const cfg = config as Record<string, unknown>;
+
+	if (!isBoolean(cfg.enabled)) {
+		errors.push(`notifications.channels.${channelId}.webhook.enabled must be a boolean`);
+	}
+
+	if (!cfg.enabled) {
+		return { enabled: false };
+	}
+
+	if (!isString(cfg.url) || cfg.url.trim().length === 0) {
+		errors.push(`notifications.channels.${channelId}.webhook.url must be a non-empty string`);
+	}
+
+	if (cfg.headers !== undefined) {
+		if (!isObject(cfg.headers)) {
+			errors.push(`notifications.channels.${channelId}.webhook.headers must be an object`);
+		} else {
+			for (const [key, value] of Object.entries(cfg.headers)) {
+				if (!isString(value)) {
+					errors.push(`notifications.channels.${channelId}.webhook.headers.${key} must be a string`);
+				}
+			}
+		}
+	}
+
+	if (errors.length > 0) {
+		throw new ConfigValidationError(errors);
+	}
+
+	const result: any = {
+		enabled: cfg.enabled,
+		url: cfg.url,
+	};
+
+	if (cfg.headers) result.headers = cfg.headers;
+
+	return result;
+}
+
 function validateNotificationChannel(channel: unknown, channelId: string): NotificationChannel {
 	const errors: string[] = [];
 
@@ -1318,6 +1360,16 @@ function validateNotificationChannel(channel: unknown, channelId: string): Notif
 		}
 	}
 
+	if (channel.webhook) {
+		try {
+			result.webhook = validateWebhookConfig(channel.webhook, channelId);
+		} catch (error) {
+			if (error instanceof ConfigValidationError) {
+				throw error;
+			}
+		}
+	}
+
 	return result;
 }
 
@@ -1657,8 +1709,9 @@ function validateNotificationChannelProviders(config: Config): void {
 		const hasDiscord = channel.discord?.enabled;
 		const hasNtfy = channel.ntfy?.enabled;
 		const hasTelegram = channel.telegram?.enabled;
+		const hasWebhook = channel.webhook?.enabled;
 
-		if (!hasEmail && !hasDiscord && !hasNtfy && !hasTelegram) {
+		if (!hasEmail && !hasDiscord && !hasNtfy && !hasTelegram && !hasWebhook) {
 			errors.push(`Notification channel '${channelId}' is enabled but has no providers configured`);
 		}
 	}

src/config.ts

@@ -2,6 +2,7 @@ import { EmailProvider } from "./providers/email";
 import { DiscordProvider } from "./providers/discord";
 import { NtfyProvider } from "./providers/ntfy";
 import { TelegramProvider } from "./providers/telegram";
+import { WebhookProvider } from "./providers/webhook";
 import { Logger } from "../logger";
 import type { NotificationChannel, NotificationEvent, NotificationProvider } from "../types";
 
@@ -38,6 +39,10 @@ export class NotificationChannelManager {
 				channelProviders.push(new TelegramProvider(channel.telegram));
 			}
 
+			if (channel.webhook?.enabled) {
+				channelProviders.push(new WebhookProvider(channel.webhook));
+			}
+
 			if (channelProviders.length > 0) {
 				this.providers.set(channelId, channelProviders);
 				Logger.info("Notification channel initialized", {

src/notifications/channel-manager.ts

@@ -1,4 +1,5 @@
 export { NotificationManager } from "./manager";
 export { EmailProvider } from "./providers/email";
 export { DiscordProvider } from "./providers/discord";
-export type { EmailConfig, NotificationEvent, DiscordConfig, TelegramConfig } from "../types";
+export { WebhookProvider } from "./providers/webhook";
+export type { EmailConfig, NotificationEvent, DiscordConfig, TelegramConfig, WebhookConfig } from "../types";