# How to Add a Custom Notification Provider to Uptime Kuma

> Easily add custom notification providers to Uptime Kuma. Extend the NotificationProvider class and register your service for enhanced alerting. Learn how now.

- Repository: [Louis Lam/uptime-kuma](https://github.com/louislam/uptime-kuma)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Extend the `NotificationProvider` base class in `server/notification-providers/`, implement the `send()` method, and register your class in [`server/notification.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification.js) to add custom alerting capabilities to Uptime Kuma.**

Uptime Kuma supports extensible alerting through a modular notification provider system. By implementing a small JavaScript class that conforms to the existing provider interface, you can integrate proprietary webhooks, internal APIs, or niche messaging services directly into the monitoring workflow.

## Understanding the Notification Architecture

Uptime Kuma’s notification system relies on three core components working in sequence. First, the abstract **`NotificationProvider`** class in [`server/notification-providers/notification-provider.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification-providers/notification-provider.js) defines the contract that all providers must follow, including utility methods for HTTP requests and template rendering. Second, concrete implementations such as `Webhook` or `Discord` in the same directory extend this base and contain the actual API integration logic. Finally, the **`Notification`** class in [`server/notification.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification.js) maintains a static registry (`providerList`) populated during server initialization; when a monitor triggers an alert, `Notification.send()` routes the request to the appropriate provider based on the `notification.type` field stored in the database.

## Step-by-Step Implementation Guide

### Create the Provider Class

Create a new file in `server/notification-providers/` (for example, [`custom-webhook.js`](https://github.com/louislam/uptime-kuma/blob/main/custom-webhook.js)). Your class must extend `NotificationProvider`, set a unique `name` property, and implement the `async send()` method. The `send()` method receives four arguments: the notification configuration object, the generated message string, optional monitor metadata (`monitorJSON`), and optional heartbeat data (`heartbeatJSON`).

```javascript
// server/notification-providers/custom-webhook.js
const NotificationProvider = require("./notification-provider");
const axios = require("axios");

class CustomWebhook extends NotificationProvider {
    // Unique identifier referenced in the database and UI
    name = "customwebhook";

    async send(notification, msg, monitorJSON = null, heartbeatJSON = null) {
        // Use Liquid templating support from the base class
        const text = await this.renderTemplate(
            notification.bodyTemplate ?? "{{msg}}", 
            msg, 
            monitorJSON, 
            heartbeatJSON
        );

        const payload = {
            alert: text,
            monitor: monitorJSON,
            timestamp: heartbeatJSON?.time
        };

        // Automatically respects proxy settings from notification_proxy env var
        const config = this.getAxiosConfigWithProxy({
            headers: { "Content-Type": "application/json" },
            timeout: 10000
        });

        try {
            await axios.post(notification.webhookURL, payload, config);
            return "Sent Successfully.";
        } catch (error) {
            // Leverage base class error handling for consistent logging
            this.throwGeneralAxiosError(error);
        }
    }
}

module.exports = CustomWebhook;

```

Key implementation details:
- The **`name`** property must be unique across all providers; it maps directly to the `type` column in the database.
- **`renderTemplate()`** processes Liquid syntax (e.g., `{{msg}}`, `{{monitor.name}}`) using the same engine as built-in providers.
- **`getAxiosConfigWithProxy()`** returns an Axios configuration object that automatically incorporates proxy settings from the `NOTIFICATION_PROXY` environment variable.
- **`throwGeneralAxiosError()`** standardizes error formatting and stack traces for the Uptime Kuma logs.

### Register Your Provider in the Notification Registry

Open [`server/notification.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification.js) and locate the `init()` method (approximately lines 7-33). Import your new class and instantiate it inside the `list` array. The initialization loop automatically adds your provider to the static `providerList` object using the `name` property as the key.

```javascript
// server/notification.js
const CustomWebhook = require("./notification-providers/custom-webhook");

class Notification {
    static providerList = {};

    static init() {
        const list = [
            // ... existing providers ...
            new CustomWebhook(),
        ];

        for (let item of list) {
            this.providerList[item.name] = item;
        }
    }

    static async send(notification, msg, monitorJSON = null, heartbeatJSON = null) {
        const provider = this.providerList[notification.type];
        if (provider) {
            return await provider.send(notification, msg, monitorJSON, heartbeatJSON);
        }
        throw new Error("Unknown notification type");
    }
}

```

After modifying [`notification.js`](https://github.com/louislam/uptime-kuma/blob/main/notification.js), restart the Uptime Kuma server (or restart your Docker container) to execute `Notification.init()` and load the new provider into memory.

### (Optional) Add Frontend UI Support

To surface your provider in the web interface’s “Add Notification” dropdown, create a corresponding Vue component in `src/components/notifications/forms/` following the pattern of existing providers like [`webhook.vue`](https://github.com/louislam/uptime-kuma/blob/main/webhook.vue). The frontend stores the selected provider type in the same `type` field used by the backend registry, ensuring seamless integration without additional API modifications.

## Key Methods and Utilities from the Base Class

When extending `NotificationProvider`, you inherit several utilities that ensure consistency with Uptime Kuma’s networking and templating stack:

- **`async renderTemplate(templateString, msg, monitorJSON, heartbeatJSON)`**: Renders Liquid templates with access to monitor and heartbeat variables.
- **`getAxiosConfigWithProxy(baseConfig)`**: Merges your Axios configuration with global proxy settings, ensuring compliance with network policies.
- **`throwGeneralAxiosError(error)`**: Converts Axios errors into standardized exceptions that the Uptime Kuma logger can parse and display in the dashboard.

Refer to [`server/notification-providers/notification-provider.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification-providers/notification-provider.js) for the full implementation of these helpers, and examine [`server/notification-providers/webhook.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification-providers/webhook.js) for a production-ready example of how to structure HTTP requests and handle authentication headers.

## Summary

- **Extend `NotificationProvider`** in a new file under `server/notification-providers/` and set a unique `name` property.
- **Implement `async send()`** to handle the actual API call, using base class utilities for templating and proxy support.
- **Register the class** in [`server/notification.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification.js) by importing it and adding an instance to the `list` array inside `init()`.
- **Restart the server** to load the provider into the static `providerList` registry.
- **Optionally extend the frontend** by adding a Vue form component if UI visibility is required.

## Frequently Asked Questions

### What file should I edit to register a new notification provider?

Edit [`server/notification.js`](https://github.com/louislam/uptime-kuma/blob/main/server/notification.js) and add your provider class instance to the `list` array inside the `static init()` method. This registration step is mandatory; without it, the backend cannot resolve the provider by its `type` string when dispatching alerts.

### Do I need to modify the database schema to add a custom provider?

No. Uptime Kuma stores the provider identifier in the existing `type` column of the notification table as a plain string. As long as your class sets a unique `name` property (e.g., `name = "myprovider"`), the system will recognize and route alerts to your implementation without migrations.

### How do I access monitor metadata inside the `send()` method?

The `send()` method receives `monitorJSON` and `heartbeatJSON` as the third and fourth arguments. These objects contain the monitor’s configuration, current status, latency, and heartbeat timestamp. Use `this.renderTemplate()` to interpolate these values into your message payload using Liquid syntax like `{{monitor.name}}` or `{{heartbeat.status}}`.

### Can my custom provider respect the global proxy settings?

Yes. Call `this.getAxiosConfigWithProxy()` from your `send()` method and pass the result as the configuration object to your HTTP client (e.g., Axios). This helper automatically checks the `NOTIFICATION_PROXY` environment variable and applies the appropriate proxy agent to the request, maintaining parity with built-in providers.