Browser Push Notifications for a Django Website

For DjangoTricks, and some other websites, I intentionally didn't set email notifications when a feedback message arrived – I didn't want to pay for an email server or spam my inbox. While checking the messages in the database from time to time, sometimes I found out about them too late.

Last weekend, I decided to implement Web Push notifications to get notified about the feedback in my OS, just like in this example:

This tutorial walks through adding Web Push notifications to a Django project from scratch. When a visitor submits a feedback form the site owner receives a native browser notification — even if the admin tab is closed — thanks to a service worker and a Huey background task.

How it works

Push Notifications work in such a way: at first, people who want to get notifications need to subscribe to the notifications in their browser. The subscribers are stored on the push notification servers and also their identifiers are stored in Django website database. Whenever we need to send the messages to those subscribers, we send them to push notification server that passes the message to all subscribers if their browsers are open at the moment. If the browsers are closed at that moment, the message's TTL (time to live) in seconds set long enough, and the message is not expired yet, they will get the message later.

The push service depends on the browser:

• Chrome - Google's FCM (Firebase Cloud Messaging) — fcm.googleapis.com
• Firefox - Mozilla Autopush — updates.push.services.mozilla.com
• Safari - Apple Push Notification Service (APNs)

The two standard Web Push prerequisites are a VAPID key pair (identifies your server
to the push service) and a service worker (a background JS script that receives the
push and shows the notification even when the tab is closed).

The workflow would be as follows:

• I as a superuser visit the Django administration page that has sw.js file with a service worker and a JavaScript to subscribe to notifications.
• JavaScript request Notification permission. I accept it.
• JS calls pushManager.subscribe() with the VAPID public key.
• JS POSTs the subscription to /notifications/push/subscribe/.
• Django stores it in PushSubscription model.

Visitor submits feedback form

• A view saves FeedbackMessage to the database.
• transaction.on_commit queues a Huey task.
• Huey task calls pywebpush - browser's push service (FCM / Mozilla).
• Push service wakes the service worker.
• Service worker shows a native OS notification.
• Clicking it opens the Django admin change page.

Prerequisites

• Django project using Huey for background tasks
• Python virtual environment

Install two dependencies:

(.venv)$ pip install pywebpush py-vapid

• pywebpush is the library to communicate with the Push Notification server.
• py-vapid will only be needed once to generate keys.

You'll need HTTPS to test the Web Push notifications if your host is not 127.0.0.1. If you use a custom domain in your /etc/hosts, such as djangotricks.localhost, you will also need to set up HTTPS with mkcert.

Step 1. The Feedback App

Create feedback app with FeedbackMessage model that will store submitted feedback messages:

# myproject/apps/feedback/models.py
from django.conf import settings
from django.db import models
from django.utils.translation import gettext_lazy as _


class FeedbackMessage(models.Model):
    created_at = models.DateTimeField(_("Created at"), auto_now_add=True)
    submitter_name = models.CharField(_("Submitter name"), max_length=200)
    submitter_email = models.EmailField(_("Submitter email")
    content = models.TextField(_("Content")

    class Meta:
        verbose_name = _("Feedback Message")
        verbose_name_plural = _("Feedback Messages")
        ordering = ("-created_at",)

    def __str__(self):
        return _("Feedback message from {}").format(self.submitter_name)

Create the form:

# myproject/apps/feedback/forms.py
from django import forms
from django.utils.translation import gettext_lazy as _
from .models import FeedbackMessage


class FeedbackMessageForm(forms.ModelForm):
    class Meta:
        model = FeedbackMessage
        fields = [
            "content",
            "submitter_name",
            "submitter_email",
        ]
        widgets = {
            "content": forms.Textarea(
                attrs={
                    "rows": 5, 
                    "placeholder": _("Your message")
                }
            ),
        }
        labels = {
            "submitter_name": _("Your name"),
            "submitter_email": _("Your email"),
        }

Create a view to handle that form:

# myproject/apps/feedback/views.py
from django.db import transaction
from django.shortcuts import render, redirect
from django.urls import reverse
from .forms import FeedbackMessageForm
from .tasks import send_feedback_push_notification


def feedback_form(request):
    if request.method == "POST":
        form = FeedbackMessageForm(data=request.POST)
        if form.is_valid():
            message = form.save(commit=False)
            if request.user.is_authenticated:
                message.user = request.user
            message.save()

            transaction.on_commit(
                lambda: send_feedback_push_notification(message.pk)
            )

            return redirect(reverse("feedback:complete"))
    else:
        form = FeedbackMessageForm()

    return render(request, "feedback/form.html", {"form": form})


def feedback_complete(request):
    return render(request, "feedback/complete.html")

Create the app config, migrations, templates, URLs, and Django administration for it.

Step 2. VAPID keys

Generate the key pair once. These stay on the server and are never committed to version
control.

(.venv)$ vapid --gen
(.venv)$ vapid --applicationServerKey --private-key private_key.pem

--gen writes private_key.pem and public_key.pem to the current directory.

The private_key.pem file will contain the key like:

-----BEGIN PRIVATE KEY-----
<Multiline private key data>
-----END PRIVATE KEY-----

--applicationServerKey prints the base64url-encoded public key the browser needs, such as:

Application Server Key = <Public key data as base64url>

For the secrets.json or .env file where you store your secrets, you will need the content of <Private key data with newlines removed> and <Public key data as base64url>.

{
    ...
    "VAPID_PRIVATE_KEY": "<Private key data with newlines removed>",
    "VAPID_PUBLIC_KEY": "<Public key data as base64url>"
}

Don't commit the *.pem files or the secrets to the Git repo!

Step 3. Django settings

# myproject/settings.py

### WEB PUSH ###

VAPID_PRIVATE_KEY = get_secret("VAPID_PRIVATE_KEY")
VAPID_PUBLIC_KEY  = get_secret("VAPID_PUBLIC_KEY")
VAPID_ADMIN_EMAIL = "[e-mail]"

Step 4. The Notifications App

Create notifications app with the PushSubscription model to track the Push notification subscribers:

# myproject/apps/notifications/models.py
from django.conf import settings
from django.db import models
from django.utils.translation import gettext_lazy as _


class PushSubscription(models.Model):
    """One browser push subscription for one device."""

    created_at  = models.DateTimeField(_("Created at"), auto_now_add=True)
    user = models.ForeignKey(
        _("User"),
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="push_subscriptions",
    )
    endpoint = models.TextField(_("Endpoint"), unique=True)
    p256dh = models.TextField(_("Browser ECDH public key"))
    auth = models.TextField(_("16-byte auth secret")) 

    class Meta:
        verbose_name = _("Push Subscription")
        verbose_name_plural = _("Push Subscriptions")
        ordering = ("-created_at",)

    def __str__(self):
        return f"{self.user} — {self.endpoint[:60]}"

Create app configuration, migrations, and Django administration for it.

Step 5. Subscribe / unsubscribe views

Create the views that will be called after the user subscribes or unsubscribes to Push notifications. Also a view for the service worker sw.js:

# myproject/apps/notifications/views.py
import json

from django.contrib.auth.decorators import login_required
from django.contrib.staticfiles import finders
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_POST

from .models import PushSubscription


@login_required
@require_POST
def push_subscribe(request):
    try:
        data     = json.loads(request.body)
        endpoint = data["endpoint"]
        p256dh   = data["keys"]["p256dh"]
        auth     = data["keys"]["auth"]
    except (KeyError, json.JSONDecodeError):
        return JsonResponse({"error": "Invalid subscription data"}, status=400)

    PushSubscription.objects.update_or_create(
        endpoint=endpoint,
        defaults={"user": request.user, "p256dh": p256dh, "auth": auth},
    )
    return JsonResponse({"status": "subscribed"})


@login_required
@require_POST
def push_unsubscribe(request):
    try:
        endpoint = json.loads(request.body)["endpoint"]
    except (KeyError, json.JSONDecodeError):
        return JsonResponse(
            {"error": "Invalid data"}, 
            status=400
        )

    PushSubscription.objects.filter(
        user=request.user, 
        endpoint=endpoint,
    ).delete()
    return JsonResponse({"status": "unsubscribed"})


def service_worker(request):
    """Serve sw-feedback.js as sw.js at the admin root"""
    path = finders.find("admin/js/sw-feedback.js")
    with open(path) as fh:
        content = fh.read()
    return HttpResponse(
        content, 
        content_type="application/javascript"
    )

Step 6. Wire URLs into myproject/urls.py

Plug the notification views into URLs:

# myproject/apps/notifications/urls.py
from django.urls import path
from . import views

app_name = "notifications"

urlpatterns = [
    path("push/subscribe/", views.push_subscribe,   name="push_subscribe"),
    path("push/unsubscribe/", views.push_unsubscribe, name="push_unsubscribe"),
]

The service worker URL must be mounted at the same prefix as ADMIN_URL so its scope
covers the admin. Add both patterns before the admin.site.urls line:

# myproject/urls.py
from notifications import views as notifications_views

urlpatterns = [
    # ...
    path(
        f"{settings.ADMIN_URL}sw.js",
        notifications_views.service_worker,
        name="admin_service_worker",
    ),
    path(
        "notifications/",
        include("notifications.urls", namespace="notifications"),
    ),
    path(settings.ADMIN_URL, admin.site.urls),
    # ...
]

Step 7. Service worker JavaScript

Save as myproject/static/admin/js/sw-feedback.js:

self.addEventListener("push", function (event) {
  const data    = event.data ? event.data.json() : {};
  const title   = data.title || "New feedback message";
  const options = {
    body: data.body || "",
    icon: "/static/admin/img/icon-yes.svg",
    data: { url: data.url || "/" },
  };
  event.waitUntil(
    self.registration.showNotification(title, options)
  );
});

self.addEventListener("notificationclick", function (event) {
  event.notification.close();
  event.waitUntil(
    clients.openWindow(event.notification.data.url)
  );
});

Step 8. Admin subscription JavaScript

Save as myproject/static/admin/js/push-subscribe.js:

(function () {
  "use strict";

  // Injected by the Django template override in Part 9.
  const VAPID_PUBLIC_KEY = window.VAPID_PUBLIC_KEY;
  const SUBSCRIBE_URL    = window.PUSH_SUBSCRIBE_URL;
  const UNSUBSCRIBE_URL  = window.PUSH_UNSUBSCRIBE_URL;
  const ADMIN_URL        = window.ADMIN_URL;

  // Tracks the endpoint last registered on the server so we can delete it even
  // when the browser subscription has already been silently revoked (e.g. user
  // cleared site data or the push subscription expired without blocking).
  const STORAGE_KEY = "pushSubscriptionEndpoint";

  // Read the CSRF token from the hidden input injected by {% csrf_token %}.
  // Do not use the cookie: this project has CSRF_USE_SESSIONS = True.
  const CSRF_TOKEN = document.querySelector("[name=csrfmiddlewaretoken]")?.value || "";

  function urlBase64ToUint8Array(base64String) {
    const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
    const base64  = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
    const rawData = atob(base64);
    return Uint8Array.from([...rawData].map((c) => c.charCodeAt(0)));
  }

  function post(url, body) {
    return fetch(url, {
      method:  "POST",
      headers: { "Content-Type": "application/json", "X-CSRFToken": CSRF_TOKEN },
      body:    JSON.stringify(body),
    });
  }

  async function syncSubscription() {
    if (!VAPID_PUBLIC_KEY) return;
    if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;

    const registration = await navigator.serviceWorker.register(
      "/" + ADMIN_URL + "sw.js",
      { scope: "/" + ADMIN_URL }
    );
    await navigator.serviceWorker.ready;

    const storedEndpoint = localStorage.getItem(STORAGE_KEY);
    const existing = await registration.pushManager.getSubscription();

    // The browser subscription was revoked (user blocked notifications, cleared
    // site data, or the subscription expired) but the server record still exists
    // — delete it using the endpoint we stored at subscription time.
    if (storedEndpoint && (!existing || existing.endpoint !== storedEndpoint)) {
      await post(UNSUBSCRIBE_URL, { endpoint: storedEndpoint });
      localStorage.removeItem(STORAGE_KEY);
    }

    // Already subscribed and the server already knows about this endpoint.
    if (existing && existing.endpoint === storedEndpoint) return;

    const permission = await Notification.requestPermission();
    if (permission !== "granted") return;

    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly:      true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });

    await post(SUBSCRIBE_URL, subscription.toJSON());
    localStorage.setItem(STORAGE_KEY, subscription.endpoint);
  }

  document.addEventListener("DOMContentLoaded", syncSubscription);
})();

localStorage is the key to reliable unsubscription. Notification.permission alone cannot detect silent revocations — when a user clears site data or a push subscription expires, the permission may still read "granted" while the browser-side subscription is gone. By storing the endpoint at subscribe time and comparing it on every page load, the script can call UNSUBSCRIBE_URL with the old endpoint even after the browser subscription object has disappeared.

Step 9. Context processor

A context processor injects the VAPID globals into every admin template response.

Create myproject/apps/notifications/context_processors.py:

from django.conf import settings
from django.urls import reverse


def push_notifications(request):
    """Inject push-notification globals into every admin page."""

    if not request.path.startswith(f"/{settings.ADMIN_URL}"):
        return {}

    if not settings.VAPID_PUBLIC_KEY:
        return {}

    return {
        "push_vapid_public_key": settings.VAPID_PUBLIC_KEY,
        "push_subscribe_url": reverse("notifications:push_subscribe"),
        "push_unsubscribe_url": reverse("notifications:push_unsubscribe"),
        "push_admin_url": settings.ADMIN_URL,
    }

Register it in the template settings:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            os.path.join(BASE_DIR, "myproject", "templates"),
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                # ...
                "myproject.apps.notifications.context_processors.push_notification_settings",
            ],
        },
    },
]

Step 10. Inject globals via admin/base_site.html

Override myproject/templates/admin/base_site.html. If one already exists, add the extrahead block; otherwise create the file extending Django's built-in template:

{% extends "admin/base_site.html" %}
{% load static %}

{% block extrahead %}
  {# ... any existing content such as a favicon include ... #}
  {% if push_vapid_public_key %}
    {% csrf_token %}
    <script nonce="{{ request.csp_nonce }}">
      window.VAPID_PUBLIC_KEY = "{{ push_vapid_public_key }}";
      window.PUSH_SUBSCRIBE_URL =  "{{ push_subscribe_url }}";
      window.PUSH_UNSUBSCRIBE_URL = "{{ push_unsubscribe_url }}";
      window.ADMIN_URL = "{{ push_admin_url }}";
    </script>
    <script src="{% static 'admin/js/push-subscribe.js' %}"></script>
  {% endif %}
{% endblock %}

Step 11. Huey task

# myproject/apps/feedback/tasks.py
import json

from django.conf import settings
from django.urls import reverse
from huey.contrib.djhuey import db_task


@db_task()
def send_feedback_push_notification(feedback_message_id):
    from pywebpush import webpush, WebPushException

    from feedback.models import FeedbackMessage
    from notifications.models import PushSubscription

    private_key = settings.VAPID_PRIVATE_KEY
    if not private_key:
        return

    if not (message := FeedbackMessage.objects.filter(
        pk=feedback_message_id
    ).first()):
        return

    admin_url = settings.WEBSITE_URL + reverse(
        "admin:feedback_feedbackmessage_change",
        args=(message.pk,)
    )
    content = message.content
    body = content[:120] + (
        "..." if len(content) > 120 else ""
    )
    payload = json.dumps({
        "title": f"{message.submitter_name}:",
        "body":  body,
        "url":   admin_url,
    })

    dead_endpoints = []
    for sub in PushSubscription.objects.all():
        try:
            webpush(
                subscription_info={
                    "endpoint": sub.endpoint,
                    "keys": {"p256dh": sub.p256dh, "auth": sub.auth},
                },
                data=payload,
                vapid_private_key=private_key,
                vapid_claims={"sub": f"mailto:{settings.VAPID_ADMIN_EMAIL}"},
            )
        except WebPushException as exc:
            # 410 Gone / 404 Not Found means the subscription has expired
            if exc.response is not None and exc.response.status_code in (404, 410):
                dead_endpoints.append(sub.endpoint)

    if dead_endpoints:
        PushSubscription.objects.filter(
            endpoint__in=dead_endpoints,
        ).delete()

The Huey task is already called from the view in feedback app via transaction.on_commit. Using
on_commit ensures the task is only queued after the database row is fully committed, so the task always finds the message when it runs.

Step 12. Content Security Policy

If the project uses Django CSP, two directives need adjusting:

CSP_WORKER_SRC  = ["'self'"]   # allows service worker registration from this origin
CSP_CONNECT_SRC = ["'self'"]   # allows the subscribe POST fetch

The pywebpush HTTP call to the external push service (FCM, Mozilla) runs server-side
inside the Huey worker process and is not subject to the browser's CSP.

User experience

It' safest to keep the body of the message up to 120 characters long - the rest will likely be cut on different OSes or browsers.

You can check the current status of notification permissions by:

Notification.permission // should be "granted", not "default" or "denied"

Based on that you can write a specific message in the User Interface what to do if the permission has been denied.

If you have many different types of notifications, you would set the configuration in a Django website. And let the visitor subscribe to the notifications in the browser once. Then your Huey tasks would check the notification settings and trigger send according messages to the subscribers.

For example, for DjangoTricks website, I would allow subscribing to new tricks, blog posts, and goodies in the notification configuration, and the visitors would grant permission to Web Push notifications just once.

Privacy and security

Messages themselves are stored on the Web Push servers encrypted, but back in the OS they are shown in plain text, and can be seen by people standing behind the user or possibly read out by other apps (or viruses) which have permissions to access OS notifications.

Practical recommendations for sensitive content:

• Send a generic notification ("You have a new message") and make the user open the app to see the actual content — this is what most banking/healthcare apps do.
• If you do include content, keep it minimal — avoid full message text, Personally Identifiable Information (PII), medical info, etc.
• Make sure your VAPID keys are securely stored and rotated if compromised.
• Set a short TTL (time-to-live) on the push message so it doesn't sit on Google's servers long if the device is offline.

For anything regulated (HIPAA, GDPR, financial data), the safest approach is the generic notification pattern, since you have no control over how the OS handles notification display and history once it leaves the browser.

OS permissions

For notification receivers, the permissions can be denied for the Browser globally as well.

One can set or unset them on MacOS at Settings ➔ Notifications ➔ Google Chrome (or another browser analogically) or on Windows at Focus Assist / Notification settings.

Marketing perspective

Opt-in: When asking for push notifications without context, only 5–25% would grant the permission. If the permission is asked in the UI at first and the reason is given, about 60% would grant the permission.

Opt-out: On average, nearly 8–10% of subscribers opt out from web push notifications per year. Even just 1 push notification per week leads to 10% of users disabling notifications. 46% of users disable notifications if they receive more than 6 notifications.

Final words

The technique of Web Push is not trivial, but with the help of py-vapid and pywebpush, it becomes manageable. The best use cases for push notifications are those where a SaaS project or a web platform suggests to use this technique intentionally: when waiting for something to happen, such as a new comment, a reply to a message, a new task to do from another person, or a new post of a favorite author who writes irregularly.

---

Cover picture by cottonbro studio