The service worker explained simply: the engine behind web push

Every web push guide, at some point, asks you to upload a file to the root of your domain. It is called a service worker, it usually has a name like natom-sw.js, and most tutorials dismiss it in one line: "upload it and move on". Then notifications do not arrive, and nobody knows where to look.

This article explains what that file does, why it has to live exactly there, and the three or four ways it goes wrong. You do not need to code: you need to understand the mechanism, because the mechanism decides whether your pushes arrive or not.

The problem a service worker solves

A web page lives as long as it is open. Close the tab, and all the code of that page stops existing. That has been the model of the web for thirty years, and it is also why, for a long time, a site could not "call you" when you were not there.

Push notifications need exactly the opposite: something that keeps listening even when the site is closed, the browser is in the background, or the phone is in a pocket. That something is the service worker.

A service worker is a small JavaScript program that the browser installs for your domain and keeps aside. It has no window, no page, you never see it. The browser wakes it up only when something concerning it happens, for instance a notification arriving, lets it do its job, and puts it back to sleep.

From the point of view of whoever runs a site, this is the important part: the service worker is the only piece of your site that exists even when nobody is looking at it.

What happens when a push goes out

It is worth following the full journey of a notification, because the service worker sits right in the middle.

1. You write a title and text in the Natom dashboard and press send.
2. Natom hands the message to the browser's push service (Google for Chrome, Apple for Safari, Mozilla for Firefox). Every subscriber has an "address" at that service, created when they opted in.
3. The push service delivers the message to the reader's device.
4. The reader's browser, even if closed, wakes up your domain's service worker and hands it the message.
5. The service worker reads title, text, image and link, and asks the operating system to display the notification.
6. The reader clicks: the service worker wakes up again, opens the link, and records the click.

If step 4 fails, that is, if the browser cannot find a valid service worker for your domain, the notification dies right there. No visible error, no warning, nothing. That is why "pushes are not arriving" is almost always a service worker problem, and almost never a sending problem.

Why it must live in the root

Here is the rule that confuses most people. A service worker can only control the pages that live below the path it was loaded from. Load it from yoursite.com/js/sw.js and it controls only yoursite.com/js/ and its subfolders. Load it from yoursite.com/sw.js and it controls the whole site.

That is why every push platform asks you to put it in the domain root. It is not a preference, it is a browser rule: a service worker in a subfolder will not receive notifications for the home page, for the articles, for anything outside that folder.

It is also why a CDN or a plugin cannot "host" the service worker for you: it must answer from your domain, at yoursite.com/natom-sw.js. Natom's WordPress plugin, for instance, physically writes it into the site's main folder for exactly this reason.

What it actually contains

Opening the file is less scary than it sounds. A push service worker does three things, and Natom's code does exactly those three and nothing else:

It listens for the "push" event. When a message arrives, it reads it (a small packet with title, text, icon, image and link) and calls the browser function that displays the notification.

It listens for the click. When the reader taps the notification, it closes it, opens the link in the browser, and sends a signal to Natom to count the click. That is where CTR statistics come from.

It counts deliveries. In a small, randomly chosen share of cases, it sends a "this notification was shown" signal. From that sample Natom estimates impressions without recording billions of events. We will come back to this in another article, but it is why statistics stay light even on sites with hundreds of thousands of subscribers.

That is all. No library, no framework, about forty lines. This is deliberate: every extra line in the service worker is one more place where something can break silently.

The four ways it goes wrong

In order of frequency, from what we see on sites that join Natom.

1. The file is missing, or not in the root

The most common case. The technician uploads it into a subfolder, or into the server root while the domain points to another folder. Check: open yoursite.com/natom-sw.js in the browser. You must see JavaScript code. If you see a 404 page, or the site's home page, the file is not where it should be.

2. It is served as a page, not as a script

Some CMSs intercept every address and answer with an HTML page, even for files. The browser asks for the service worker, receives HTML, and refuses to register it. Check: again by opening the address, if you see the site layout around the code, or the code does not appear at all, this is it. You need a server rule that lets that file through untouched.

3. An old service worker holds the spot

If the site used another notification service, its service worker is still registered in readers' browsers. Two service workers on the same domain fight over notifications, and usually the wrong one wins. Natom's snippet removes old subscriptions before creating a new one, but the old file must be removed from the server, otherwise it keeps getting registered. We cover this in detail in the migration guide.

4. The site is not on HTTPS

Service workers only work over secure connections. A site on HTTP cannot register one, full stop. If your site still has pages served over HTTP, those pages will never be able to subscribe anyone.

A note on changing the file

The browser keeps a copy of the service worker and updates it on its own, periodically checking whether the file on the server has changed. This means two practical things. First: when you update the file, readers receive it within about a day, not instantly. Second: you must never let the server cache that file for long periods, or updates never arrive. A short cache, or none, is the right choice.

The thirty-second check

Before writing to anyone, run these four checks in order. They cover 95% of the cases we see.

1. Open yoursite.com/natom-sw.js in the browser. If you see JavaScript code starting with a comment and containing the word push, the file is there and served correctly. If you see a site page or an error, stop here: this is the problem.
2. Check the padlock. The address must start with https://. If the browser flags mixed content or the page is on http://, service workers do not start.
3. Open the developer tools (F12 in Chrome), Application tab, Service Workers entry. You must see exactly one service worker registered for your domain, with status "activated". If you see two, one belongs to the old provider and must be removed. If you see none, go back to step 1.
4. Send a test push from the Natom dashboard to your test device (the one marked with ?natom_test=1). If it arrives, the full path works; if it does not but the three points above are fine, the problem is the browser permission, not the service worker.

Thirty seconds, no tools to install, and you know exactly whom to ask what.

What to take away

The service worker is the piece of your site that lives even when the site is closed, and it is the only one that can receive a notification. It must live in the domain root, it must be served as JavaScript, it must be the only one, and the site must be on HTTPS. If any of these four conditions is missing, pushes do not arrive, and nobody tells you.

The good news is that it takes ten seconds to check: open yoursite.com/natom-sw.js and see what answers. If you run WordPress, the Natom plugin does all of this by itself and tells you in its settings page whether the file responds correctly.

If you would rather start from the basics, our article on what web push notifications are and how they work puts the service worker in the full picture. And when you are ready, the free account includes everything you need to try it, service worker included.