Push Notifications

Push notifications allow your status page visitors to receive instant browser notifications when incidents occur or component status changes — even when they're not actively viewing the page.

How Push Notifications Work

┌─────────────────────────────────────────────────────────────┐
│                 Push Notification Flow                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. User visits status page                                  │
│            │                                                 │
│            ▼                                                 │
│  2. Browser asks: "Allow notifications?"                     │
│            │                                                 │
│            ▼                                                 │
│  3. User clicks "Allow" → Subscription created               │
│            │                                                 │
│            ▼                                                 │
│  4. ATStatus stores push subscription                        │
│            │                                                 │
│            ▼                                                 │
│  5. When incident occurs:                                    │
│     ATStatus → Push Service → User's Browser                │
│            │                                                 │
│            ▼                                                 │
│  6. User sees notification (even if browser minimized)       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Enabling Push Notifications

Step 1: Generate VAPID Keys

Push notifications use VAPID (Voluntary Application Server Identification) keys for authentication. Generate these keys once:

# Using npx (recommended)
npx web-push generate-vapid-keys

# Output:
# Public Key: BM0h...
# Private Key: abc123...

Step 2: Configure Environment Variables

Add the keys to your .env file:

# Push Notification Configuration
VAPID_PUBLIC_KEY=BM0h...your-public-key...
VAPID_PRIVATE_KEY=abc123...your-private-key...
VAPID_SUBJECT=mailto:admin@yourdomain.com

Step 3: Enable in Admin Settings

1. Navigate to Admin → Settings → Notifications
2. Enable Push Notifications
3. Configure notification triggers (optional)
4. Click Save

Notification Triggers

Configure which events trigger push notifications:

User Experience

Subscribing

When push notifications are enabled, visitors see a subscribe button on the status page. Clicking it triggers the browser's permission prompt.

Unsubscribing

Users can unsubscribe by:

• Clicking the subscribe button again (toggles)
• Revoking notification permission in browser settings
• Clearing browser data

Notification Content

Push notifications include:

• Title: Incident title or component name
• Body: Status update message
• Icon: Your status page logo
• Badge: Small notification badge icon
• Action: Click to open status page

// Example notification payload
{
  "title": "🔴 Major Outage: API Service",
  "body": "We are investigating reports of API errors...",
  "icon": "/logo.png",
  "badge": "/badge.png",
  "data": {
    "url": "https://status.example.com/incidents/inc_123"
  }
}

Service Worker

Push notifications require a service worker. ATStatus includes a pre-configured service worker at /sw-push.js that handles:

• Receiving push events
• Displaying notifications
• Handling notification clicks
• Background sync for offline support

Privacy Considerations

Troubleshooting

Notifications Not Appearing

• Check VAPID keys are correctly set in .env
• Verify HTTPS is configured (required for push)
• Check browser notification permissions
• Ensure service worker is registered (check DevTools → Application)
• Check browser-specific restrictions (Focus Mode, DND, etc.)

Permission Denied

• User may have blocked notifications for your domain
• Check browser settings → Site Settings → Notifications
• User needs to manually reset permission

Mobile Not Working

• iOS requires Safari 16.4+ and the site must be added to Home Screen
• Android Chrome works on supported sites
• Check device notification settings for the browser app

Browser Support