How to Add a Custom Notification Provider in Uptime Kuma

Introduction

Uptime Kuma is an open-source, versatile, and customizable self-hosted monitoring tool that supports various notifications. This guide will walk you through integrating a custom notification channel.

This guide assumes that you have a notification provider whose service can be accessed through an API to send your notifications through your account.

Step 1: Clone the Uptime Kuma Repository

Start by cloning the Uptime Kuma repository and navigating into it:

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma

Step 2: Install Dependencies

Ensure you have the necessary dependencies installed. Browse to this project and run:

npm run setup

Step 3: Create the Notification Form

1. Navigate to the src/components/notifications directory:

2. Create a new file for example CustomNotify.vue, <CustomNotify> being the name of your custom notification. Copy and Paste the following template to your file:

<template>
   <div class="mb-3">
       <label for="customnotify-username" class="form-label">{{
           $t("your CustomNotify Username")
       }}</label>

       <input
           id="username"
           v-model="$parent.notification.customnotificationUsername"
           type="text"
           class="form-control"
           placeholder="Your Username"
           required
       />
   </div>

   <div class="mb-3">
       <label for="customnotify-password" class="form-label">{{
           $t("your CustomNotify  Password")
       }}</label>
       <HiddenInput
           id="password"
           v-model="$parent.notification.customnotifyPassword"
           :required="true"
       ></HiddenInput>
   </div>

   <div class="mb-3">
       <label for="customnotify-recpient" class="form-label">{{
           $t("CustomNotify  recepient")

       }}</label>

       <input
           id="phoneNumber"
           v-model="$parent.notification.customnotifyRecepient"
           type="text"
           class="form-control"
           placeholder="recepient address or phone number..."
           required
       />

   </div>

</template>
<script>
import HiddenInput from "../HiddenInput.vue";

export default {

   components: {
       HiddenInput,
   },

};
</script>

The above template should be customized to include the fields on the form, which capture the attributes or variables that your Notification api may require. These can include, username, api token or even password.

3. Locate NotificationDialog.vue in src/components and add your custom notification to the dropdown list:

Add the Line highlighted to register your notification on the dropdown list

4. Under the same folder, Locate the index.js file and register the notification files like below.

Import the custom notification vue file as shown.

Still under index.js, Locate the NotificationFormList, and add the line below.

By here, we are done with the Form where to customize the CustomNotify notification.

Step 4: Write the Notification Logic

Within the project, Locate the server/notification-providers and then create a new file, customNotify.js

Copy the template below and add the fields your notification service provides, and then add the url to your notification api as shown.

const NotificationProvider = require("./notification-provider");
const { DOWN, UP } = require("../../src/util");
const axios = require("axios");

class CustomNotify extends NotificationProvider {
   name = "CustomNotify";
   async send(notification, msg, monitorJSON = null, heartbeatJSON = null) {
       const username = notification.customUsername;
       const password = notification.customPassword;
       const sender = notification.customSender || "CUSTOMNOTIFY";
       const number = notification.customPhoneNumber;
       let message = msg;

       if (heartbeatJSON != null) {
           // Modify the message based on the status (UP/DOWN)
           if (heartbeatJSON["status"] === DOWN) {
               message = `Service ${monitorJSON["name"]} is down!`;
           } else if (heartbeatJSON["status"] === UP) {
               message = `Service ${monitorJSON["name"]} is back up!`;
           }
       }
       const url = `https://www.customnofy/api/v1/plain/?number=${number}&message= ${message}& username=${username}& password=${password}&sender=${sender}&priority=${"0"}`;

       try {
           const response = await axios.get(url);
           return response.data;

       } catch (error) {
           console.error(`Failed to send notification: ${error.message}`);
           throw new Error(`Failed to send notification: ${error.message}`);
       }
   }
}

module.exports = CustomNotify;

Step 5: Build and Test

1. Build the Uptime Kuma application:

npm run build

2. Start the application:

Node server/server.js

• Open Uptime Kuma in your browser (e.g., http://localhost:3001).
• Navigate to the Settings menu and click Add Notification.
• Select “CustomNotify” from the dropdown, fill in the required fields, and click Save and Test.
• Verify that the notification is successfully sent to your recipient.

Step 6: Deploy Your Changes

If you’re hosting Uptime Kuma, deploy the updated codebase to your server. Push your changes to your fork or repository and pull them on the server.

Conclusion

Integrating a custom notification in Uptime Kuma enhances its flexibility and allows you to tailor it to your monitoring needs. By following this guide, you’ve added a new notification channel, implemented its logic, and tested it successfully. Enjoy seamless and customized monitoring with Uptime Kuma!