---
title: "Web Push"
status: active
audience: [ai-agent, contributor]
language: nl
last_updated: 2026-05-07
when_to_read: "When sending push notifications from the server or MCP layer, or when troubleshooting PWA push on iOS."
---

# Patroon: Web Push

## Wat & wanneer

Gebruik Web Push voor OS-niveau notificaties die ook verschijnen wanneer de browser-tab gesloten is (b.v. Claude-vragen, sprint-completion). Gebruik het **niet** voor in-app realtime feedback — daarvoor dient de SSE/realtime/notifications-stack (`stores/notifications-store`).

## Architectuur

```
MCP / cron
  │
  ▼
POST /api/internal/push/send   ← Bearer: INTERNAL_PUSH_SECRET
  │
  ▼
lib/push-server.ts → sendPushToUser(userId, payload)
  │  • VAPID-check (disabled = warn + return)
  │  • prisma.pushSubscription.findMany
  │  • Promise.allSettled(sendOne[])
  │  • 404/410 → auto-delete stale subscription
  ▼
Web Push Service (FCM / APNS)
  │
  ▼
public/sw.js  →  showNotification + notificationclick
```

## Payload-shape

```ts
type PushPayload = {
  title: string   // max 80 tekens
  body:  string   // max 300 tekens
  url:   string   // absoluut pad ('/dashboard') of volledige URL
  tag?:  string   // dedupliceert notificaties met dezelfde tag
}
```

## Foutcodes

| Code | Betekenis | Actie |
|------|-----------|-------|
| 404 / 410 | Stale endpoint (browser heeft sub verwijderd) | Auto-delete in `sendOne` |
| 5xx | Tijdelijke fout push-service | Geen automatische retry in v1 — log + swallow |
| 401 (send-route) | Verkeerd of ontbrekend Bearer-secret | Check `INTERNAL_PUSH_SECRET` |
| 422 (send-route) | Ongeldige body | Zie payload-shape hierboven |
| 503 (send-route) | `INTERNAL_PUSH_SECRET` niet geconfigureerd | Zet env-var |

## VAPID-configuratie

Genereer sleutels eenmalig:
```bash
npx web-push generate-vapid-keys
```

Zet in `.env.local`:
```bash
NEXT_PUBLIC_VAPID_PUBLIC_KEY="<public key>"
VAPID_PRIVATE_KEY="<private key>"
VAPID_SUBJECT="mailto:admin@example.com"
INTERNAL_PUSH_SECRET="<min 32 chars, openssl rand -base64 32>"
```

Als de VAPID-envs ontbreken, returnt `sendPushToUser` vroeg met een `console.warn`; de app crasht **niet**.

## iOS-quirks

- Vereist iOS 16.4+ (Safari 16.4).
- De gebruiker moet de app eerst via **Zet op beginscherm** als PWA installeren. Push werkt niet vanuit een normale Safari-tab.
- In de EU (iOS 17.4+ na DMA) worden meldingen door Apple beperkt voor alternatieve browser-engines; test op Safari specifiek.
- `isIOSSafari()` + `!isStandalonePWA()` → `PushToggle` toont de installatie-banner in plaats van een toggle.

## Demo-users

`subscribeToPushAction` controleert `session.isDemo` en returnt zonder schrijven. Demo-gebruikers kunnen zich dus niet aanmelden voor push.

## Triggeren vanuit MCP of server-code

```ts
// Directe server-aanroep (binnen Next.js):
import { sendPushToUser } from '@/lib/push-server'
await sendPushToUser(userId, { title: 'Vraag van Claude', body: question, url: `/products/${productId}` })

// Vanuit MCP / externe service (HTTP):
await fetch(`${BASE_URL}/api/internal/push/send`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${INTERNAL_PUSH_SECRET}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId, payload: { title, body, url } }),
})
// 204 = verzonden, 503 = VAPID niet geconfigureerd
```

## Admin testroute

```bash
curl -X POST https://<host>/api/internal/push/test-send \
  -H "Cookie: <admin session cookie>"
# Vereist ingelogde admin-sessie; stuurt push naar eigen account.
```