Skip to content
ChannelWatch

Provider Plugins

ChannelWatch v1.0 includes a plugin loader for notification providers. If the built-in providers (Discord, Telegram, Slack, email, Pushover, Gotify, Matrix, and Custom Apprise) don’t cover your use case, you can drop in a third-party provider as a Python file.

How the plugin loader works

Section titled “How the plugin loader works”

At startup, ChannelWatch scans /config/plugins/notifications/ for .py files. Each file is imported, and any class that subclasses the NotificationProvider base class is registered as an available provider.

The loader is designed to fail safely:

  • If a plugin file has a syntax error or import error, ChannelWatch logs a warning and skips that file. The rest of the application starts normally.
  • Plugins are loaded once at startup. Dropping a new file into the directory while ChannelWatch is running has no effect until the next restart.
  • Plugins receive only the notification event data. They do not have access to the database or encryption keys.

Installing a plugin

Section titled “Installing a plugin”
  1. Obtain the plugin .py file from the plugin author.
  2. Place it in the /config/plugins/notifications/ directory inside your mounted config volume.
  3. Restart the ChannelWatch container.
  4. Check the startup logs to confirm the plugin loaded:
INFO  Plugin loaded: MyCustomProvider (my_plugin.py)

If the plugin failed to load, you’ll see a warning instead:

WARN  Plugin skipped: my_plugin.py — ImportError: No module named 'requests'
  1. Once loaded, the plugin appears as a provider option under Settings > Notifications.

Directory layout

Section titled “Directory layout”

Your config volume should look like this after adding a plugin:

/config/
├── settings.json
├── channelwatch.db
├── encryption.key
└── plugins/
    └── notifications/
        └── my_plugin.py

Create the plugins/notifications/ directories if they don’t exist yet.

Plugin dependencies

Section titled “Plugin dependencies”

Plugins run inside the ChannelWatch container. If your plugin imports a third-party library that isn’t bundled with ChannelWatch, the import will fail and the plugin will be skipped.

To use a plugin with external dependencies, you have two options:

  • Extend the image — create a custom Dockerfile that installs the required packages on top of the ChannelWatch base image.
  • Use only stdlib or bundled packages — write the plugin using only Python’s standard library and packages already present in the ChannelWatch image (such as httpx, apprise, and pydantic).

What plugins can and cannot do

Section titled “What plugins can and cannot do”

Plugins can:

  • Receive the full notification event (alert type, DVR id, channel info, message body)
  • Send notifications to any destination using any Python-accessible transport
  • Return a success or failure result that feeds into the delivery log

Plugins cannot:

  • Access the ChannelWatch database directly
  • Read or write encryption keys
  • Modify alert routing or suppress built-in providers
  • Be hot-reloaded without a container restart

Scope: notification providers only

Section titled “Scope: notification providers only”

In v1.0, the plugin system covers notification providers only. Alert-source plugins (custom event sources beyond Channels DVR) and UI plugins are on the roadmap but are not available in v1.0.

Section titled “Related pages”
  • Delivery Log — track delivery status for all providers including plugins
  • Custom (Apprise) — use any Apprise-supported service without writing a plugin
  • Hot Reload — what changes take effect without a restart (plugins are not hot-reloaded)