Skip to content

[feat] add ntfy as a new alert notification channel#4132

Open
Zmjjeff7 wants to merge 3 commits into
apache:masterfrom
Zmjjeff7:feat/ntfy-notification-channel
Open

[feat] add ntfy as a new alert notification channel#4132
Zmjjeff7 wants to merge 3 commits into
apache:masterfrom
Zmjjeff7:feat/ntfy-notification-channel

Conversation

@Zmjjeff7

Copy link
Copy Markdown

What is changed and how it works?

This PR adds ntfy as a new alert notification channel
(type=15) to HertzBeat. ntfy is a popular open-source HTTP-based
push-notification service that is widely used in self-hosting communities,
and it works well for receiving HertzBeat alerts on mobile devices and
desktops without depending on third-party platforms.

Backend changes

  • New handler NtfyAlertNotifyHandlerImpl in hertzbeat-alerter,
    extending AbstractAlertNotifyHandlerImpl with type id 15
  • Three new fields on NoticeReceiver: ntfyServerUrl, ntfyTopic,
    ntfyToken
  • New configurable property alerter.ntfy-default-server-url
    (default: https://ntfy.sh)

Feature highlights

  • Priority mapping — alert severity is mapped to ntfy priority levels
    (critical=5, warning=4, info/unknown=3, resolved alerts=2)
  • Emoji tags — status- and severity-aware tags
    (rotating_light + skull for critical firing, warning for warning,
    white_check_mark for resolved); the alertname is also appended as a
    plain-text tag
  • Bearer token auth — supports self-hosted ntfy instances with
    access-control tokens
  • Click action — notifications carry a click URL pointing to the
    HertzBeat console
  • Markdown body — alert content is rendered in Markdown for
    better readability on ntfy clients

Frontend changes

  • Added ntfy option to the notification receiver type dropdown
  • Three new form fields: server URL (optional, default
    https://ntfy.sh), topic (required), access token (optional)
  • Display tag in the receiver list table
  • i18n translations for en-US, zh-CN, zh-TW, ja-JP, pt-BR

Tests

Added NtfyAlertNotifyHandlerImplTest with 16 test cases covering:

  • Successful send / non-2xx response / network errors
  • URL building (custom server, default server fallback,
    trailing-slash handling)
  • Bearer token header injection
  • Priority mapping for all severity levels and resolved state
  • Tag generation for critical/warning/info/resolved cases
  • Header presence and values (Priority, Tags, Click, Markdown)

Checklist

  • I have read the Contribution Guidelines
  • I have self-reviewed my code
  • I have added unit tests covering the new feature
  • My change follows the existing alert handler conventions
    (Gotify/ServerChan style)
  • No HIP is required (new notification channel — small enhancement)
@tomsun28

Copy link
Copy Markdown
Member

hi please help fix the ci error. thanks

@Zmjjeff7 Zmjjeff7 force-pushed the feat/ntfy-notification-channel branch from 6f338b3 to e4613c6 Compare May 24, 2026 01:26
@tomsun28

Copy link
Copy Markdown
Member

hi the ci show that web-app still has the eslint error, you can run pnpm run lint:fix to fix this. https://github.com/apache/hertzbeat/actions/runs/26349762920/job/77565809007#step:6:24

Add ntfy (https://ntfy.sh) as the 16th alert notification channel
(type=15). ntfy is a popular open-source HTTP-based push notification
service widely used in self-hosting communities.

Features:
- Map alert severity to ntfy priority (critical=5, warning=4,
  info=3, resolved=2)
- Build emoji tags based on alert status and severity (rotating_light,
  skull, warning, white_check_mark, etc.)
- Support Bearer token authentication for self-hosted ntfy servers
- Click action redirects to HertzBeat console
- Default server URL configurable via alerter properties
- Render alert content in Markdown format
@Zmjjeff7 Zmjjeff7 force-pushed the feat/ntfy-notification-channel branch from fbdf04c to a78fd6a Compare May 24, 2026 02:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

3 participants