Notifications

Notifications

DOCSight can send event alerts after its own monitoring pipeline has decided that a notification is needed. Severity filters, per-event toggles, cooldowns, health hysteresis, test delivery, and event context stay in DOCSight.

Notification targets are optional. You can use the simple direct webhook path, the native Discord webhook formatting, or an Apprise API sidecar for broader provider fan-out.

Delivery options

• Direct webhook: DOCSight posts its notification payload to one configured HTTP endpoint. This works for simple ntfy, Gotify, Discord, or custom webhook setups.
• Discord webhook: Discord webhook URLs are detected and formatted as Discord embeds.
• Apprise API sidecar: DOCSight posts to an Apprise API server. Apprise then routes the alert to provider-specific targets such as Telegram, Matrix, ntfy, Gotify, Slack, Pushover, or email.

Apprise is not required for users who only want the direct webhook path.

What stays in DOCSight

DOCSight remains responsible for deciding when to notify:

• event detection and severity decisions
• severity filter
• per-event notification toggles
• global and per-event cooldowns
• health hysteresis
• test notification payloads
• event-specific context

Apprise is responsible for deciding where the alert goes once DOCSight sends it to the sidecar.

Apprise sidecar setup

1. Run an Apprise API container next to DOCSight. See Example Compose Stacks for a ready-to-copy stack.
2. Open the Apprise API UI, usually http://HOST:8000.
3. Create a persistent Apprise configuration and add your provider targets there.
4. In DOCSight, open Settings > Notifications and enable Apprise.
5. Set the Apprise API URL, config key, optional API token, and optional tags.
6. Use the DOCSight test notification button to verify delivery.

If you publish the Apprise API port beyond a trusted host, bind it to localhost behind a reverse proxy or protect it with an API token.

If the config key is empty, DOCSight posts to Apprise's stateless /notify endpoint. That mode only works when your Apprise API server has stateless target URLs configured, for example through Apprise's APPRISE_STATELESS_URLS option.

With a config key, DOCSight posts to /notify/{config_key} and Apprise uses the persistent configuration stored under that key.

Common Apprise target examples

Manage provider credentials in Apprise whenever possible, not in DOCSight.

• Telegram: tgram://BOT_TOKEN/CHAT_ID
• Matrix: matrixs://USER:PASSWORD@matrix.example.org/!room:example.org
• ntfy: ntfy://ntfy.sh/docsight-alerts
• Gotify: gotify://gotify.example.org/TOKEN
• Email: mailtos://USER:PASSWORD@smtp.example.org?to=admin@example.org

Check the upstream Apprise documentation for exact URL syntax and provider requirements.

Privacy and logging

• DOCSight sends the notification payload it already builds for alert delivery: source, timestamp, severity, event type, message, and event details.
• Apprise may forward notification data to whichever providers you configure there. Review each provider before adding it.
• DOCSight treats Apprise URL, config key, API token, and tags as sensitive or secret-adjacent settings.
• Secret fields are masked in the UI and encrypted at rest where applicable.
• Failed Apprise delivery logs identify the Apprise channel and HTTP status without exposing the full URL, config key, token, or provider credentials.

Not Home Assistant and not PWA push

Apprise delivery is only an alert target.

It does not replace DOCSight's MQTT Auto-Discovery/Home Assistant telemetry integration. Use Home Assistant for sensors and dashboards.

It also does not replace PWA/Web Push. Browser push still needs service worker handling, browser permissions, subscriptions, and click/deep-link behavior. See PWA and Offline Mode for the current PWA behavior.