Illustration of a server sending Node.js web push notifications to a browser Illustration of a server sending Node.js web push notifications to a browser

How to Send Web Push Notifications From Node.js

How to send web push notifications from Node.js with the web-push library: VAPID keys, subscriptions, sending code and error handling.

To send web push notifications from Node.js, install the web-push library, generate a VAPID key pair once, and save each browser’s push subscription in a database. Then call setVapidDetails with your keys and sendNotification with a subscription and a JSON payload. The library encrypts the message, and the browser’s push service delivers it to your service worker.

Node.js web push notifications don’t need Firebase or any paid service on the sending side. The protocol is an open standard, and the open-source web-push library handles the hard parts: VAPID signing and payload encryption. Below I cover the full flow, with code checked against web-push 4.0, the current version in November 2026.

What do you need to send Node.js web push notifications?

You need five pieces: HTTPS, a VAPID key pair, a service worker, a subscription store and a sender. Here’s what each one does.

PiecePurposeNotes
HTTPS siteService workers only run in secure contextslocalhost works for testing
VAPID key pairIdentifies your server to push servicesGenerate once; keep the private key secret
Service workerReceives the push event and shows the notificationServe it from your own domain
Subscription storeSaves each browser’s endpoint and keysOne row per browser, not per user
web-push packageEncrypts and sends each messageVersion 4 needs Node.js 16 or newer

The browser side is the same whatever language your server uses. So if you’ve read my PHP and Laravel guide, only the server code below is new.

How do you install web-push and create VAPID keys?

Install the package from npm, then generate the keys once with its command-line tool. Don’t generate new keys on every deploy, because existing subscriptions only work with the public key they were created with.

npm install web-push
npx web-push generate-vapid-keys --json

Save the two values as environment variables, for example VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. The public key goes to the browser. The private key stays on your server. My explainer on VAPID keys for web push covers what each key does and why losing the private key cuts you off from your subscribers.

How do you collect push subscriptions in the browser?

The browser creates a subscription when the visitor allows notifications. Your page registers a service worker, asks for permission on a click, calls pushManager.subscribe with your public key, and posts the result to your server.

// public/sw.js
self.addEventListener('push', (event) => {
  const data = event.data ? event.data.json() : {};
  event.waitUntil(
    self.registration.showNotification(data.title || 'New update', {
      body: data.body,
      icon: data.icon,
      data: { url: data.url || '/' }
    })
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});
// on your page, inside a button click handler
const reg = await navigator.serviceWorker.register('/sw.js');
const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: VAPID_PUBLIC_KEY // the public key string
});
await fetch('/api/subscribe', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(sub)
});

The web-push README shows the public key passed as a string, which current browsers accept. Some older tutorials convert it to a Uint8Array first; that works too. For more on scope and caching, see my guide to the service worker for web push.

How do you send a notification with web-push?

Set your VAPID details once, then call sendNotification for each subscription. Version 4 of web-push is an ES module without a default export, so import it as a namespace. On recent Node.js releases (20.19+ and 22.12+), require(‘web-push’) also works.

// server.mjs (Express)
import express from 'express';
import * as webpush from 'web-push';

webpush.setVapidDetails(
  'mailto:[email protected]',
  process.env.VAPID_PUBLIC_KEY,
  process.env.VAPID_PRIVATE_KEY
);

const app = express();
app.use(express.json());
const subscriptions = new Map(); // use a real database in production

app.post('/api/subscribe', (req, res) => {
  subscriptions.set(req.body.endpoint, req.body);
  res.sendStatus(201);
});

app.post('/api/send', async (req, res) => {
  const payload = JSON.stringify({
    title: 'New post: Node.js web push',
    body: 'Read the step-by-step guide',
    url: '/blog/nodejs-web-push/'
  });
  for (const sub of subscriptions.values()) {
    try {
      await webpush.sendNotification(sub, payload, { TTL: 3600, urgency: 'normal' });
    } catch (err) {
      if (err instanceof webpush.WebPushError && (err.statusCode === 404 || err.statusCode === 410)) {
        subscriptions.delete(sub.endpoint); // expired or unsubscribed
      } else {
        console.error(err.statusCode, err.body);
      }
    }
  }
  res.sendStatus(202);
});

app.listen(3000);

The subject must be a mailto: address or an https: URL that push services can use to contact you. The web-push README notes that Safari’s push endpoint rejects a subject pointing at https://localhost, so use a real address even in testing.

Which sendNotification options matter?

Three options matter for most sends: TTL, urgency and topic. They map to headers defined in RFC 8030, the Web Push protocol.

OptionWhat it doesDefault in web-push
TTLSeconds the push service keeps the message if the device is offlineFour weeks
urgencyvery-low, low, normal or high; affects battery-saving deliverynormal
topicReplaces an older undelivered message with the same topicNone
timeoutSocket timeout in millisecondsNone
headersExtra request headersNone

For news, a TTL of a few hours stops yesterday’s headline from arriving tomorrow. For a one-time code or alert, use a short TTL and high urgency. Also keep payloads small: RFC 8030 only requires push services to accept 4,096 bytes, so send a title, body and URL, not a full article.

How do you handle expired subscriptions and errors?

Delete a subscription when the push service answers 404 or 410. Those codes mean the subscription has expired or the visitor has unsubscribed, so retrying wastes requests. web-push throws a WebPushError with statusCode, headers and body, which makes the check simple.

Other errors need different handling:

  • 400 or 403: usually a VAPID problem, such as a key mismatch or a bad subject. Check that the public key in the browser matches the private key on the server.
  • 413: the payload is too large. Trim it.
  • 429: you’re being rate limited. Back off and retry later.

At larger lists, don’t loop with await one by one. Send in batches with a concurrency limit, or put sends on a queue such as BullMQ, so one slow endpoint doesn’t hold up everyone else. MDN’s Push API reference covers the browser side of the same flow.

Does Node.js web push reach iPhone users?

Yes. Since iOS 16.4, Safari supports web push for sites added to the Home Screen, and web-push sends to Apple’s endpoint like any other. You need a web app manifest, and the visitor must add your site to the Home Screen before they can subscribe. See how to get web push working on iPhone for the full checklist.

Should you build it yourself or use a push panel?

Build it yourself if you only need a few alerts triggered by code and you have developers to maintain them. Use a panel if marketers or editors will send campaigns, because the DIY route gives you delivery but no editor, scheduling, segments or reports.

NeedDIY with web-pushPush panel
Send an alert from codeGood fitWorks through an API
Campaign editor and schedulingYou build itIncluded
Segments and click reportsYou build itIncluded
Expired subscription cleanupYou build itHandled for you
Main costDeveloper timeSubscription or licence

If you’re on Next.js, my guide to adding web push to Next.js shows the same library inside Server Actions.

Where does LaraPush fit?

LaraPush is a self-hosted web push panel you install on your own VPS. It handles subscriptions, campaigns, scheduling, segmentation and click reports, and its REST API has no call limits, so your Node.js app can trigger sends instead of encrypting messages itself. See the features overview, the setup guide and my notes on the push notification API for developers.

The trade-offs: you run the server, the licence covers one server, and there’s no free plan. Plans start from $499 one-time; check the pricing page for current prices. For a wider view, my roundup of push notification services compares SaaS and self-hosted tools.

Frequently asked questions

Do I need Firebase to send web push from Node.js?

No. The web-push library sends straight to each browser’s push service using VAPID, so you don’t need a Firebase project or server key. Chrome subscriptions still travel through Google’s push service, but your code only needs the subscription endpoint and your VAPID keys.

Why does web-push fail with “does not provide an export named default”?

Version 4 of web-push is an ES module without a default export. Import it with import * as webpush from ‘web-push’, or import the functions you need by name, such as sendNotification and setVapidDetails.

How many notifications can Node.js send at once?

There’s no fixed limit in web-push itself; each send is one HTTPS request. Throughput depends on your server, network and concurrency. For large lists, send in batches or through a job queue, and remove subscriptions that return 404 or 410.

Can I send a push without a payload?

Yes. sendNotification accepts no payload, and the service worker still gets a push event. It must then show a notification anyway, because browsers require a visible notification for each push, so most sites send a small JSON payload instead.

What is the subject in setVapidDetails?

It’s a contact point for push services, either a mailto: email address or an https: URL. Push services can use it to reach you if your sends cause problems. Avoid an https://localhost subject, which Safari’s push endpoint rejects.

Leave a Reply

Your email address will not be published. Required fields are marked *