Skip to main content

Web Push

Web Push (RFC8030) allows ntfy to receive push notifications, even when the ntfy web app (or even the browser, depending on the platform) is closed. When enabled, the user can enable background notifications for their topics in the wep app under Settings. Once enabled by the user, ntfy will forward published messages to the push endpoint (browser-provided, e.g. fcm.googleapis.com), which will then forward it to the browser.

To configure Web Push, you need to generate and configure a VAPID keypair (via ntfy webpush keys), a database to keep track of the browser's subscriptions, and an admin email address (you):

  • web-push-public-key is the generated VAPID public key, e.g. AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890
  • web-push-private-key is the generated VAPID private key, e.g. AA2BB1234567890abcdefzxcvbnm1234567890
  • web-push-file is a database file to keep track of browser subscription endpoints, e.g. /var/cache/ntfy/webpush.db
  • web-push-email-address is the admin email address send to the push provider, e.g. sysadmin@example.com
  • web-push-startup-queries is an optional list of queries to run on startup`

Limitations:

  • Like foreground browser notifications, background push notifications require the web app to be served over HTTPS. A valid certificate is required, as service workers will not run on origins with untrusted certificates.

  • Web Push is only supported for the same server. You cannot use subscribe to web push on a topic on another server. This is due to a limitation of the Push API, which doesn't allow multiple push servers for the same origin.

To configure VAPID keys, first generate them:

$ ntfy webpush keys
Web Push keys generated.
...

Then copy the generated values into your server.yml or use the corresponding environment variables or command line arguments:

web-push-public-key: AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890
web-push-private-key: AA2BB1234567890abcdefzxcvbnm1234567890
web-push-file: /var/cache/ntfy/webpush.db
web-push-email-address: sysadmin@example.com

The web-push-file is used to store the push subscriptions. Unused subscriptions will send out a warning after 7 days, and will automatically expire after 9 days (not configurable). If the gateway returns an error (e.g. 410 Gone when a user has unsubscribed), subscriptions are also removed automatically.

The web app refreshes subscriptions on start and regularly on an interval, but this file should be persisted across restarts. If the subscription file is deleted or lost, any web apps that aren't open will not receive new web push notifications until you open then.

Changing your public/private keypair is not recommended. Browsers only allow one server identity (public key) per origin, and if you change them the clients will not be able to subscribe via web push until the user manually clears the notification permission.

No Comments
Back to top