{"id":"6a39c32f86dfe812bb057a0b","title":"Web Push Vapid","path":"how-to/technical-articles/2026-02-11-ngx-ramblers-architecture/web-push-vapid","contentMarkdown":"# 23-Jun-2026 — Web Push Notifications and VAPID Keys\n\n_____\n\nA companion to [NGX Ramblers Architecture Overview](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-02-11-ngx-ramblers-architecture). It explains the **Web Push (VAPID) keys** listed in the System Configuration section: what they are and why NGX stores them.\n\n## What they are for\n\nWeb Push (VAPID) keys are the credential that lets NGX send a browser notification to a committee member when a new message arrives in a shared inbox.\n\n## Web Push, in plain terms\n\nWeb Push is the browser standard behind notifications that appear even when the site is not open in a tab. NGX registers a small background script (a service worker) in each committee member's browser. When a new inbound message is stored, the server sends a push, and that script shows the notification and updates the unread badge.\n\nThe catch: a browser will not accept a push from just anyone. Each push travels through the browser maker's push service — Google's for Chrome, Mozilla's for Firefox, Apple's for Safari — and that service needs to know the push genuinely came from this application and not from a spammer.\n\n## Where VAPID comes in\n\nVAPID (Voluntary Application Server Identification) is how the application proves who it is. It is a pair of keys:\n\n- a **public key**, handed to the browser when a member subscribes to notifications\n- a **private key**, kept on the server and used to sign every push it sends\n\nThe push service checks the signature against the public key the browser registered, and only then delivers the message. A **subject** (a `mailto:` contact address) is included so the push service has someone to contact if there is a problem.\n\n## How NGX uses them\n\n- The keys are generated once and reused. They are stored in the central config (the `inboxPush` setting: `vapidPublicKey`, `vapidPrivateKey`, `vapidSubject`), alongside the other service credentials.\n- When a committee member turns on notifications, their browser subscribes using the public key, and NGX stores that subscription (the `inboxPushSubscriptions` collection).\n- When an inbound message is assigned to a role, NGX signs a push with the private key and sends it to each subscribed member of that role. The same signal drives the live unread badge in the admin UI.\n\n## The flow at a glance\n\n**1. Subscribe** (once, when a member turns on notifications):\n\n```mermaid\nflowchart LR\n APP1@{ icon: \"ngx:ramblers\", label: \"NGX Ramblers\", pos: \"b\", h: 48 }\n MEMBER@{ icon: \"ngx:user\", label: \"Member's browser\", pos: \"b\", h: 48 }\n STORE@{ icon: \"ngx:mongodb\", label: \"inboxPushSubscriptions\", pos: \"b\", h: 48 }\n APP1 -->|\"public VAPID key\"| MEMBER\n MEMBER -->|\"subscription: endpoint + keys\"| STORE\n```\n\n**2. Send** (each time a message arrives):\n\n```mermaid\nflowchart LR\n MSG[\"New inbound message\"]\n APP2@{ icon: \"ngx:ramblers\", label: \"NGX Ramblers\", pos: \"b\", h: 48 }\n PUSHSVC[\"Browser push service
Google · Mozilla · Apple\"]\n SW[\"Service worker
in member's browser\"]\n BADGE[\"Notification + unread badge\"]\n MSG --> APP2\n APP2 -->|\"push signed with private key\"| PUSHSVC\n PUSHSVC -->|\"verify against public key, deliver\"| SW\n SW --> BADGE\n```\n\nThe inbound flow that triggers these notifications is described in the Email Architecture section of the [architecture overview](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-02-11-ngx-ramblers-architecture).\n","contentHtml":"

23-Jun-2026 — Web Push Notifications and VAPID Keys

\n
\n

A companion to NGX Ramblers Architecture Overview. It explains the Web Push (VAPID) keys listed in the System Configuration section: what they are and why NGX stores them.

\n

What they are for

\n

Web Push (VAPID) keys are the credential that lets NGX send a browser notification to a committee member when a new message arrives in a shared inbox.

\n

Web Push, in plain terms

\n

Web Push is the browser standard behind notifications that appear even when the site is not open in a tab. NGX registers a small background script (a service worker) in each committee member's browser. When a new inbound message is stored, the server sends a push, and that script shows the notification and updates the unread badge.

\n

The catch: a browser will not accept a push from just anyone. Each push travels through the browser maker's push service — Google's for Chrome, Mozilla's for Firefox, Apple's for Safari — and that service needs to know the push genuinely came from this application and not from a spammer.

\n

Where VAPID comes in

\n

VAPID (Voluntary Application Server Identification) is how the application proves who it is. It is a pair of keys:

\n\n

The push service checks the signature against the public key the browser registered, and only then delivers the message. A subject (a mailto: contact address) is included so the push service has someone to contact if there is a problem.

\n

How NGX uses them

\n\n

The flow at a glance

\n

1. Subscribe (once, when a member turns on notifications):

\n
flowchart LR\n    APP1@{ icon: "ngx:ramblers", label: "NGX Ramblers", pos: "b", h: 48 }\n    MEMBER@{ icon: "ngx:user", label: "Member's browser", pos: "b", h: 48 }\n    STORE@{ icon: "ngx:mongodb", label: "inboxPushSubscriptions", pos: "b", h: 48 }\n    APP1 -->|"public VAPID key"| MEMBER\n    MEMBER -->|"subscription: endpoint + keys"| STORE\n
\n

2. Send (each time a message arrives):

\n
flowchart LR\n    MSG["New inbound message"]\n    APP2@{ icon: "ngx:ramblers", label: "NGX Ramblers", pos: "b", h: 48 }\n    PUSHSVC["Browser push service<br/>Google · Mozilla · Apple"]\n    SW["Service worker<br/>in member's browser"]\n    BADGE["Notification + unread badge"]\n    MSG --> APP2\n    APP2 -->|"push signed with private key"| PUSHSVC\n    PUSHSVC -->|"verify against public key, deliver"| SW\n    SW --> BADGE\n
\n

The inbound flow that triggers these notifications is described in the Email Architecture section of the architecture overview.

\n"}