New Notifications

Introduction

Out of the box, Monika support a multitude of notification channels, from chat applications such as Slack, Discourse, Microsoft Teams, Google Chats to email based platform such as Mailgun, to generic webhooks and the SMTP protocol (full list can be found in Notifications here). Should you have a favorite tool we haven't supported, we invite you to add it to Monika's growing list. Here's how.

Prerequisites

There are few requirements to start adding a new notification to Monika:

1. Some basic TypeScript may be helpful.
2. Some familiarity with git is required to clone and create pull requests.
3. A GitHub account to fork and clone the Monika open source repository.
4. An environment already set up for development in JavaScript/TypeScript. See the project README for an overview.
5. A code editor such as Vim or Visual Studio Code is recommended.

Add a New Notification

1. Create a new file in the packages/notification/channel directory that satisfies the NotificationChannel type from the packages/notification/channel/index.ts file and implement the new notification.

1 type NotificationChannel<T = any> = {
2   validator: Joi.AnySchema
3   send: (notificationData: T, message: NotificationMessage) => Promise<void>
4   sendWithCustomContent?: (
5     notificationData: T,
6     customContent: T
7   ) => Promise<void>
8   additionalStartupMessage?: (notificationData: T) => string
9 }

2. Import the implemented notification file to the packages/notification/channel/index.ts file.

 import * as whatsapp from './whatsapp'

3. Register it to the channels variable in the same file. The key in the channels variable will be used in the Monika configuration to identify the notification type.

1 export const channels: Record<string, NotificationChannel> = {
2   desktop,
3   'google-chat': googlechat,
4   // ...
5   whatsapp,
6   workplace,
7 }

Events

You can access different type of events from the message argument from the send function. It available on the meta.type property. Some of the events you need to handle are:

• start: This is a "start-of-monitoring" message when monika is first fired up.
• termination: A termination message occurs as Monika is shutting down.
• incident: Incident is an alert triggered whenever we've detected an incident in the probes.
• recovery: Recovery alert indicates the probe has recovered from the previous incident.
• status-update: Status update is a daily summary message of the probe events.

This is the example how we handle the different events.

1 function getContent(
2   { body, meta, summary }: NotificationMessage,
3   notificationType: string
4 ): Content {
5   switch (notificationType) {
6     case 'start':
7       ... code to send start notifications
8     case 'termination':
9       ... code to send termination notifications
10     case `incident`:
11       ... code to send incident notifications

This is where you can get creative and really customize the look and feel of the notifications. You can use icons, widgets, fonts and colors of your choice. In the example googlechat.ts below, you can see how headers, text coloring are used to create the incident notifications. Your choices and available options will vary depending on your application. Refer to the app's development/integration documentation for more information.

1 case 'incident':
2       return {
3         cards: [
4           {
5             header: {
6               title: 'Monika Notification',
7               subtitle: `New ${notificationType} from Monika`,
8               imageUrl: 'https://bit.ly/3kckaGO',
9             },
10             sections: [
11               {
12                 widgets: [
13                   {
14                     textParagraph: {
15                       text: `<b>Message: <font color=#ff0000>Alert!</font></b> ${summary}`,
16                     },
17                   },
18                   {
19                     textParagraph: {
20                       text: `<b>URL:</b> <a href>${url}</a>`,
21                     },
22                   },
23                   {
24                     textParagraph: {
25                       text: `<b>Time:</b> ${time}`,
26                     },
27                   },
28                   {
29                     textParagraph: {
30                       text: `<b>From:</b> ${monikaInstance}`,
31                     },
32                   },
33                 ],
34               },
35             ],
36           },
37         ],
38       }

Validating

Monika users have the option to use JSON schema validation from their favorite editors. This is super convenient and provide useful real time feedback. Therefore it is mandatory to add a new schema to reflect your changes, otherwise, your new notification type will not be recognized and flagged as an unknown type.

Update the json schema in src/monika-config-schema.json to be able to validate your new notification.

In the example above, the google chat schema validation may look something like:

1 {
2   "title": "Google Chat",
3   "type": "object",
4   "required": ["id", "type", "data"],
5   "additionalProperties": false,
6   "properties": {
7     "id": {
8       "type": "string",
9       "description": "Unique notification id",
10       "default": "google-chat-01"
11     },
12     "type": {
13       "const": "google-chat"
14     },
15     "data": {
16       "type": "object",
17       "description": "Data for your payload",
18       "additionalProperties": false,
19       "required": ["url"],
20       "properties": {
21         "url": {
22           "$ref": "#/definitions/urlFormat",
23           "description": "The webhook URL for your google chat",
24           "examples": [
25             "https://chat.googleapis.com/v1/spaces/XXXXX/messages?key=1122334455"
26           ]
27         }
28       }
29     }
30   }
31 },

For further documentation on json schemas, you can visit the json schema website here.

Testing

To make sure your integration won't break in the future, add your unit test(s) into the folder test/components/notification.test.ts. This will also ensure that all your code behaves as designed. We use Mocha.js testing framework and Chai.js' expect for assertion and checking.

Documentation

To wrap it up, add some documentation about your new app, specifically how to set it up for others to use. Users will love you for it.

That's it. Finally push your changes and create a pull request back to Monika's mainline repository and we'll merge it.