Skip to main content

Implementing Web Push Notifications in Firefox using VAPID and Mozilla Push Service

 You have successfully implemented a web push notification system. It works flawlessly in Chrome via Firebase Cloud Messaging (FCM). However, when you test the implementation in Firefox, the subscription either fails silently, or the browser throws a cryptic DOMException.

This is a notorious bottleneck for web developers and marketing tech engineers. Browsers implement the W3C Push API specification differently. While Chrome is heavily integrated with FCM and often forgives legacy configuration patterns, Firefox relies on its own infrastructure and strictly enforces protocol standards.

To achieve reliable delivery across all platforms, your application must correctly interface with the Mozilla Push Service using strictly compliant VAPID configurations.

The Root Cause of Firefox Delivery Failures

The divergence between Chrome and Firefox stems from how they handle push service routing and authentication. Chrome routes messages through fcm.googleapis.com. Firefox routes messages through the Mozilla Push Service, typically hitting an endpoint at updates.push.services.mozilla.com.

Historically, Chrome allowed developers to use proprietary GCM/FCM sender IDs. Firefox enforces the IETF standard RFC 8292: VAPID (Voluntary Application Server Identification). VAPID allows your server to identify itself to the push service without requiring a proprietary developer account.

Delivery failures in the Firefox Push API typically occur for three reasons:

  1. Malformed Application Server Keys: Firefox's PushManager.subscribe() method strictly requires the applicationServerKey to be a Uint8Array. Passing a raw base64-encoded string works in some older WebKit/Blink implementations but will immediately fail in Firefox.
  2. Invalid VAPID Subjects: The Mozilla Push Service actively drops incoming payloads if the VAPID token does not contain a valid mailto: or https: URL in the sub (subject) claim.
  3. Payload Encryption Mismatches: Firefox expects exact adherence to the Web Push Message Encryption standard (RFC 8291). If the Crypto-Key or Encryption headers are malformed, the push service returns a 400 Bad Request.

Implementing the Cross-Browser Solution

To solve this, we must configure both the client-side subscription logic and the server-side payload dispatcher to strictly adhere to VAPID standards.

Step 1: Client-Side Key Conversion

Before calling the Firefox Push API, you must convert your VAPID public key from a base64, URL-safe string into a Uint8Array. This ensures the cryptographic signature matches the exact byte sequence expected by the Mozilla Push Service.

Create a robust conversion utility in your frontend application:

/**
 * Converts a base64 string to a Uint8Array for PushManager subscription.
 * @param {string} base64String 
 * @returns {Uint8Array}
 */
const urlBase64ToUint8Array = (base64String) => {
  const padding = '='.repeat((4 - base64String.length % 4) % 4);
  const base64 = (base64String + padding)
    .replace(/-/g, '+')
    .replace(/_/g, '/');

  const rawData = window.atob(base64);
  const outputArray = new Uint8Array(rawData.length);

  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
};

Step 2: Registering the Service Worker and Subscribing

Next, register your service worker and request a subscription from the browser's PushManager. By passing the converted Uint8Array to the applicationServerKey property, Firefox will successfully negotiate with the Mozilla Push Service.

const PUBLIC_VAPID_KEY = 'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBtc3sHkX5aEev_k1QukO2O00';

const subscribeToWebPush = async () => {
  if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
    console.error('Web Push is not supported in this browser.');
    return null;
  }

  try {
    const registration = await navigator.serviceWorker.register('/sw.js');
    await navigator.serviceWorker.ready;

    const existingSubscription = await registration.pushManager.getSubscription();
    if (existingSubscription) {
      return existingSubscription;
    }

    const convertedVapidKey = urlBase64ToUint8Array(PUBLIC_VAPID_KEY);
    
    // Firefox strictly validates this object
    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: convertedVapidKey
    });

    console.log('Successfully subscribed to Mozilla Push Service:', subscription);
    return subscription;

  } catch (error) {
    console.error('Failed to subscribe to the Firefox Push API:', error);
    throw error;
  }
};

Step 3: Server-Side Dispatch with Node.js

On your backend, you must utilize a library that handles the complex RFC 8291 payload encryption. The web-push library for Node.js is the industry standard for this task.

The configuration here is where most Firefox implementations fail. The subject must be a highly specific, valid format.

import webpush from 'web-push';

// VAPID keys should be generated once via `webpush.generateVAPIDKeys()` 
// and stored securely in environment variables.
const VAPID_SUBJECT = 'mailto:admin@yourdomain.com'; // CRITICAL: Must be valid for Firefox
const VAPID_PUBLIC_KEY = process.env.VAPID_PUBLIC_KEY;
const VAPID_PRIVATE_KEY = process.env.VAPID_PRIVATE_KEY;

webpush.setVapidDetails(
  VAPID_SUBJECT,
  VAPID_PUBLIC_KEY,
  VAPID_PRIVATE_KEY
);

/**
 * Dispatches a push notification to a specific browser endpoint.
 * @param {Object} subscription - The subscription object from the client
 * @param {Object} payloadData - The data to send
 */
export const sendNotification = async (subscription, payloadData) => {
  try {
    const payload = JSON.stringify(payloadData);
    
    // web-push automatically detects the endpoint (Mozilla vs FCM) 
    // and formats the Authorization header accordingly.
    const response = await webpush.sendNotification(subscription, payload);
    
    console.log(`Notification dispatched successfully. Status: ${response.statusCode}`);
    return response;
  } catch (error) {
    if (error.statusCode === 410) {
      console.warn('Subscription has expired or is no longer valid.');
      // Logic to remove subscription from your database goes here
    } else {
      console.error('Error dispatching to Mozilla Push Service:', error);
    }
    throw error;
  }
};

Deep Dive: How the Mozilla Push Service Processes VAPID

When the web-push library executes sendNotification, it analyzes the endpoint URL inside the client's subscription object. If the URL contains mozilla.com, it constructs a JWT (JSON Web Token) signed by your VAPID private key.

This JWT is appended to the request as an Authorization: WebPush header, alongside an Application-Server-Key header containing your public key. The Mozilla Push Service validates this signature. If the signature matches, and the subject inside the JWT is a valid mailto: or https: string, Firefox allows the message into its queue.

Furthermore, Firefox enforces userVisibleOnly: true. This constraint ensures that background processes cannot receive push messages without surfacing a visual notification to the user, preventing malicious battery drain or silent tracking.

Handling Common Pitfalls and Edge Cases

The 410 Gone Error

Browsers aggressively cycle push subscriptions. If a user clears their site data in Firefox, or if the Mozilla Push Service determines a token has been inactive for too long, your backend will receive a 410 Gone HTTP status. Your system must catch this specific status code and prune the dead subscription from your database immediately to prevent IP reputation throttling from Mozilla.

Handling pushsubscriptionchange

Firefox occasionally rotates the push subscription unilaterally for security reasons. Your service worker must listen for the pushsubscriptionchange event to seamlessly update the backend without requiring user interaction.

// Inside sw.js (Service Worker)
self.addEventListener('pushsubscriptionchange', async (event) => {
  event.waitUntil(
    self.registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(PUBLIC_VAPID_KEY)
    }).then(async (newSubscription) => {
      // Send the new subscription to your backend
      await fetch('/api/update-subscription', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          oldEndpoint: event.oldSubscription ? event.oldSubscription.endpoint : null,
          newSubscription: newSubscription
        })
      });
    })
  );
});

Payload Size Limits

The Mozilla Push Service restricts encrypted payload sizes to 4KB. While FCM sometimes allows slightly larger payloads depending on the routing context, Firefox strictly drops packets exceeding 4096 bytes. If you need to transmit rich media like large images, send a lightweight JSON payload containing a URL, and fetch the asset dynamically within the service worker's push event listener.

Conclusion

Achieving parity across browser notifications requires moving away from vendor-specific legacy methods and strictly adopting W3C standards. By properly encoding your VAPID keys to a Uint8Array, supplying valid subject identifiers, and handling subscription lifecycle events gracefully, your web push notifications will route reliably through the Mozilla Push Service.

Labels: