PWA push notifications: a guide that also explains why they fail

Push notifications help a web application become an operational tool. Without them, a new lead or urgent finding waits until someone opens the browser. Implementation is relatively straightforward; diagnosis is harder because a failure may leave little visible evidence.

The notification delivery chain

1. The user grants browser notification permission.
2. The page registers a service worker.
3. A push subscription is created with the public VAPID key.
4. The endpoint and subscription keys are saved on the server.
5. The server signs and sends a message using the private VAPID key.
6. The browser's push service wakes the service worker, which displays the notification.

Any link can fail. Start diagnosis by identifying the last verified stage, not by assuming a successful provider response proves that a notification appeared on the phone.

A common suspect: an outdated service worker

When delivery is accepted but the phone stays silent, inspect the active service worker version. An older worker may remain active while existing tabs are open. Keep a visible version in the worker and verify the browser actually activates updates; do not serve the worker from an application cache.

Check the subscription associated with the active registration. Recreating it can help isolate a stale configuration, but it is a diagnostic step, not proof that the worker was the cause. Also inspect notification settings and the device's focus or battery restrictions.

iOS has its own conditions

• Web push on supported iOS versions requires a web app added to the Home Screen, not an ordinary browser tab.
• The permission request must follow a direct user action, such as pressing a notification button.
• Provide a valid manifest for an installable standalone experience.
• Removing the installed web app can invalidate its subscription; handle expired subscriptions explicitly.

Server-side cleanup of expired subscriptions

Push services return 404 or 410 when a subscription no longer exists. Remove or deactivate those records so dead endpoints do not overwhelm delivery statistics. Track each outcome separately: accepted delivery, expired subscription, transient failure and configuration failure.

A test button pays for itself

An administrator-only test notification control should return the actual dispatch result: how many messages were accepted, how many failed and the safe error category. It makes it easier to distinguish server delivery problems from device display problems. Confirmation on the target device is still necessary.

Content rules for operational notifications

Use a short title that names the event, a body with the identifying context, and a link to the relevant record. A notification that requires searching after opening becomes noise and will be disabled. Test Hebrew direction and truncation in the operating system's compact notification view.

Conclusion

Reliable push is a lifecycle problem as much as a coding problem: worker versions, live subscriptions, permissions and mobile edge cases all matter. Monitoring the chain and providing a safe internal test tool turns silent surprises into diagnosable failures.