Architecture

What happens end to end

The current Nudgr flow has four actors:

• your site
• the browser and its service worker
• the Nudgr API
• your backend webhook receiver

The full path is:

1. Your site creates a Nudgr SDK instance with a project API key
2. The SDK registers the service worker and asks the Nudgr API for the project VAPID public key
3. The browser creates a push subscription and the SDK sends that subscription to Nudgr
4. Nudgr stores the subscription under the project
5. Your server calls POST /v1/notifications/send with the same project API key
6. Nudgr sends a web push request to each stored browser subscription
7. If webhook delivery is enabled, Nudgr POSTs notification.sent or notification.failed to your backend
8. When a user clicks the notification, the service worker opens the URL and reports the click back to Nudgr
9. Nudgr validates that click payload and POSTs notification.clicked to your backend

Sequence diagram

sequenceDiagram
  participant Site as Developer Site
  participant SW as Browser / Service Worker
  participant API as Nudgr API
  participant Backend as Developer Backend

  Site->>SW: initialize SDK and register service worker
  Site->>API: GET /v1/vapid-key/self
  API-->>Site: VAPID public key
  SW->>SW: create browser push subscription
  Site->>API: POST /v1/subscriptions
  API-->>Site: subscription stored

  Backend->>API: POST /v1/notifications/send
  API->>SW: send web push payload
  API->>Backend: webhook notification.sent / notification.failed
  SW->>SW: show notification
  SW->>API: POST /v1/events/click
  API->>Backend: webhook notification.clicked

Core objects

Project

A project owns:

• one API key
• one VAPID key pair
• webhook configuration
• all subscriptions and notifications under that project

Subscription

A subscription represents one browser push endpoint for one project.

Stored fields include:

• endpoint
• p256dh
• auth
• user agent

Notification

A notification is a send record created when your backend calls:

POST /v1/notifications/send

It stores:

• title
• body
• URL
• icon
• sent count
• failed count

Webhook event

A webhook event is a signed POST sent from Nudgr to your backend.

Current event types:

• notification.sent
• notification.failed
• notification.clicked

Important semantics

notification.sent does not mean the user saw the notification

It only means the push service accepted the request.

notification.clicked is best effort

Click tracking depends on the browser service worker successfully sending a follow-up request. If the user is offline or the browser interrupts the request, the click may not be recorded.

The project API key and webhook secret are different

• the project API key authenticates your site and backend to Nudgr
• the webhook secret lets your backend verify that webhook requests really came from Nudgr

The service worker is part of the data path

Without a working service worker:

• the browser cannot receive push
• click tracking cannot happen

Common failure points

Subscribe step fails

Usually caused by:

• notification permission denied
• missing service worker file
• unsupported browser

Send step succeeds but users see nothing

Usually caused by:

• browser not really subscribed
• stale subscription
• environment mismatch between test site and stored project

Click events never arrive

Usually caused by:

• service worker not installed correctly
• push payload missing click tracking metadata
• interrupted click report request

Webhook delivery fails

Usually caused by:

• invalid webhook URL
• receiver timeout
• signature verification using a parsed body instead of the raw body

Related docs

• Quick Start
• Service Worker
• Webhooks
• Troubleshooting