Web Push (VAPID)

RoundTrip uses the Web Push protocol with VAPID (Voluntary Application Server Identification) keys to deliver push notifications to technicians' devices via the PWA. This allows the app to send notifications even when the browser or app is not actively open — critical for technicians who need to know about new job assignments while they are in the field.

---

What Web Push Does

Notification	Trigger	Recipient
New job assigned	Ticket assigned to technician	Technician's device
Job updated	Ticket details changed	Assigned technician
Urgent job alert	High/Urgent priority ticket created	All available technicians

Web Push complements SignalR. SignalR delivers real-time notifications while the app is open. Web Push delivers notifications when the app is in the background or closed.

---

How VAPID Works

1. On PWA install, browser prompts user for notification permission
   │
   │ User grants permission
   ▼
2. Browser generates a unique push subscription
   └─ Contains endpoint URL (browser vendor push service)
   └─ Encryption keys specific to this device/browser
   │
   │ PWA sends subscription to RoundTrip API
   ▼
3. RoundTrip stores subscription in database against TenantUser
   │
   ▼
4. When a notification needs to be sent:
   │
   │ Handler → INotificationPushService.PushAsync(userId, payload)
   │
   ▼
5. API signs the push message with VAPID private key
   └─ Proves the message is from RoundTrip (not a third party)
   │
   │ Sends to browser vendor push service endpoint
   ▼
6. Browser vendor push service (Google FCM, Mozilla, Apple)
   └─ Delivers notification to device
   └─ Even if browser is closed
   │
   ▼
7. PWA service worker receives push event
   └─ Displays system notification
   └─ User taps notification → app opens to relevant ticket

---

Configuration

Key Vault Secrets

Secret Name	Config Key	Purpose
VapidKeys--PublicKey	VapidKeys:PublicKey	Sent to browser when registering push subscription
VapidKeys--PrivateKey	VapidKeys:PrivateKey	Used server-side to sign push messages
VapidKeys--Subject	VapidKeys:Subject	Contact URI identifying the app server — typically mailto:admin@roundtrips.app

App Service Settings

Setting Name	Value
VapidKeys__PublicKey	@Microsoft.KeyVault(VaultName=kv-roundtrip-production;SecretName=VapidKeys--PublicKey)
VapidKeys__PrivateKey	@Microsoft.KeyVault(VaultName=kv-roundtrip-production;SecretName=VapidKeys--PrivateKey)
VapidKeys__Subject	@Microsoft.KeyVault(VaultName=kv-roundtrip-production;SecretName=VapidKeys--Subject)

Generating New VAPID Keys

If VAPID keys ever need to be regenerated (e.g. key compromise), use the web-push CLI:

npx web-push generate-vapid-keys

This outputs a new Public Key and Private Key pair. Update both Key Vault secrets and redeploy.

:::warning Regenerating VAPID Keys Invalidates All Subscriptions All existing push subscriptions stored in the database become invalid when VAPID keys are regenerated. Users will need to re-grant notification permission and re-register their push subscriptions on next app load. Only regenerate keys if absolutely necessary. :::

---

PWA Service Worker

The service worker (sw.js or equivalent) handles incoming push events on the device:

self.addEventListener('push', event => {
  const data = event.data?.json();

  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: '/icons/icon-192.png',
      badge: '/icons/badge-72.png',
      data: { url: data.url },  // URL to open on notification tap
    })
  );
});

self.addEventListener('notificationclick', event => {
  event.notification.close();
  event.waitUntil(
    clients.openWindow(event.notification.data.url)
  );
});

---

Troubleshooting

Notifications not appearing on device

1. Check browser notification permission — must be Allowed (not Blocked or Default)
2. Check that the push subscription was registered — look for the subscription in the database against the user's TenantUserId
3. Check App Service logs for errors when sending the push — look for VAPID signing errors
4. Check that VapidKeys__PublicKey and VapidKeys__PrivateKey match — a mismatched pair causes all pushes to fail silently

iOS PWA push notifications

iOS Safari requires PWA to be installed to the home screen before push notifications work. Users who access RoundTrip in Safari browser without installing will not receive push notifications. This is an Apple platform limitation, not a RoundTrip bug.

---

Planned Enhancements

Enhancement	Notes
Notification preference management	Allow technicians to choose which notification types they receive
Notification history	Store last N notifications per user — visible in-app
Rich notifications	Include ticket details, client name, address in notification payload