Introduction to Notifly Plugins

[!caution] Plugins are not available in the cloud (serverless) version of Notifly.

Yandex Cloud Functions run each request in an isolated environment and do not allow dynamically loading .so files. Plugins only work in the self-hosted build (see Installation). For the cloud version it is recommended to use the following instead of plugins:

• Webhooks — receiving events from external systems;
• Email Inbox — receiving emails as notifications;
• WebScript — events from the frontend without a backend;
• Heartbeat and Active monitors — built-in alert sources;
• MCP server — integrations with AI and third-party scripts via ready-made tools.

[!warning] Plugins are currently supported only on Linux and MacOS due to a current limitation in Go.

Description

This documentation is generally intended for plugin developers. If you only wanted to use an existing plugin, you should refer to the plugin developer’s documentation.

Notifly provides built-in plugin functionality, built on top of the go plugin system. It is designed to extend Notifly’s functionality.

Features

• One plugin instance per user
• Registration of custom HTTP handlers
• Sending messages on behalf of a channel
• YAML-based configuration system in the WebUI
• Persistent storage for each user’s plugin instance
• Displaying dynamically generated instructions to users

Use cases

• Receiving webhooks from GitHub, Travis CI, etc.
• Polling new channels via RSS, Atom, or other sources.
• Extending WebUI functionality.
• Delivering alert notifications.

Getting started

First, let’s look at a minimal notifly plugin example; you can copy this sample code to load your own plugin:

package main

import (
  "github.com/notifly/plugin-api"
)

// GetNotiflyPluginInfo — returns information about the notifly plugin
func GetNotiflyPluginInfo() plugin.Info {
  return plugin.Info{
    Name:       "minimal plugin",
    ModulePath: "github.com/Notifly/example/minimal",
  }
}

// Plugin — plugin instance
type Plugin struct{}

// Enable — implements plugin.Plugin
func (c *Plugin) Enable() error {
  return nil
}

// Disable — implements plugin.Plugin
func (c *Plugin) Disable() error {
  return nil
}

// NewNotiflyPluginInstance — creates a plugin instance for the user's context.
func NewNotiflyPluginInstance(ctx plugin.UserContext) plugin.Plugin {
  return &Plugin{}
}

func main() {
  panic("this should be built as go plugin")
}

This program exports two functions: GetNotiflyPluginInfo and NewNotiflyPluginInstance; Notifly uses these to obtain plugin metadata and to create plugin instances for each user.

GetNotiflyPluginInfo must return plugin.Info, containing descriptive information about the current plugin; all fields are optional except ModulePath (the module path of this plugin), which is used to distinguish different plugins.

NewNotiflyPluginInstance is called with plugin.UserContext for each user on startup and every time a new user is added; the plugin should return a plugin instance that satisfies the plugin.Plugin interface. More functionality can be implemented by implementing additional interfaces from the plugin-api package.