Dokumentation
1. Token im Backend erzeugen
Deine App hat einen Signaturschlüssel. Dein Backend weiß ohnehin, wer angemeldet ist, und signiert damit ein kurzlebiges Token, das diesen Nutzer benennt. Der Schlüssel gelangt nie in einen Browser.
import { createHmac } from 'node:crypto'
function mintToken(appId, userId, signingKey, ttlSeconds = 900) {
const payload = {
aid: appId,
sub: userId, // your own user id
exp: Math.floor(Date.now() / 1000) + ttlSeconds,
// tnt: workspaceId, // optional: one tenant's bell
}
const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url')
const signature = createHmac('sha256', signingKey).update(encoded).digest('base64url')
return `${encoded}.${signature}`
}2. Die Glocke auf der Seite platzieren
<script src="https://notifybell.altixcode.com/embed/notify-bell.js" defer></script>
<notify-bell app-id="app_…" token="…" api-url="https://notifybell.altixcode.com"></notify-bell>Es handelt sich um ein Custom Element – es funktioniert also in React, Vue, Svelte, Rails oder einer einfachen HTML-Seite gleich gut. Setze beim Erneuern einfach das Attribut token neu, und das Element verbindet sich von selbst wieder.
3. Aus dem Backend veröffentlichen
curl -X POST https://notifybell.altixcode.com/api/v1/apps/APP_ID/notifications \
-H "Authorization: Bearer nb_…" \
-H "Content-Type: application/json" \
-d '{
"subscriberId": "usr_99812",
"title": "Deployment completed",
"body": "Your production build v1.4.2 was deployed.",
"category": "system",
"actionUrl": "https://app.example.com/deployments/123",
"dedupeKey": "deploy-123"
}'Der Abonnent wird beim ersten Veröffentlichen angelegt, ein Nutzerabgleich ist also nicht nötig. Übergib einen dedupeKey, und ein erneuter Versuch deines Job-Runners lässt die Glocke nicht zweimal klingeln.
Server- und React-SDKs
Lieber ein typisierter Client als rohes HTTP? @notifybell/node veröffentlicht, sendet Broadcasts und erstellt Abonnenten-Tokens, mit Wiederholung bei 429 und 5xx. @notifybell/react rendert die Glocke als Komponente und erneuert ihr Token, bevor es abläuft. Beide stehen unter MIT-Lizenz und sind auf npm.
npm install @notifybell/node @notifybell/react
// server
import { NotifyBell, mintSubscriberToken } from '@notifybell/node'
const app = new NotifyBell({ apiKey: process.env.NOTIFYBELL_API_KEY }).app('app_123')
await app.publish({ subscriberId: user.id, title: 'Your export is ready' })
const token = mintSubscriberToken({ appId: 'app_123', subscriberId: user.id, signingKey })
// React
import { NotifyBell } from '@notifybell/react'
<NotifyBell appId="app_123" token={token} getToken={fetchFreshToken} />Gestaltung
Das Element wird in einen Shadow Root gerendert: Dein CSS kann es nicht versehentlich umgestalten, und seine Styles können nicht in deine Seite durchsickern. Drei Bereiche sind bewusst nach außen geöffnet:
notify-bell::part(bell) { color: #64748b; }
notify-bell::part(badge) { background: #2563eb; }
notify-bell::part(panel) { border-radius: 4px; }Sprache, Gestaltung und Ereignisse
Attribute: app-id, token, api-url, lang. Die Eigenschaft strings übersetzt jedes Wort (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required …), strings.categories benennt Kategorien. Ereignisse: notify-bell:click und notify-bell:action sind abbrechbar – mit preventDefault() leiten Sie in der App weiter, statt einen Tab zu öffnen; notify-bell:token-expired fordert ein neues Token an. Das Theme kommt aus dem Dashboard; Ihre eigenen CSS-Variablen am Element (--nb-accent, --nb-badge, --nb-radius) und ::part(bell | badge | panel | toast) haben Vorrang.
const bell = document.querySelector('notify-bell')
bell.strings = {
title: 'Benachrichtigungen',
markAll: 'Alle gelesen',
categories: { billing: 'Rechnungen' },
}
bell.addEventListener('notify-bell:click', (event) => {
event.preventDefault() // route in-app instead of opening a tab
router.push(event.detail.data.path)
})
bell.addEventListener('notify-bell:token-expired', async () => {
bell.setAttribute('token', await fetchFreshToken())
})
/* CSS */
notify-bell { --nb-accent: #0f766e; --nb-badge: #b91c1c; --nb-radius: 8px; }Webhooks
Legen Sie auf der Seite „Webhooks“ einen Endpunkt pro App an, und NotifyBell sendet Ereignisse per POST: notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Jede Anfrage trägt NotifyBell-Signature (t=Zeitstempel,v1=HMAC-SHA256 von "Zeitstempel.Body" mit Ihrem Endpunkt-Geheimnis); weisen Sie alles ab, was nicht verifiziert oder älter als fünf Minuten ist. Eine Antwort außerhalb 2xx wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden erneut versucht, dann als fehlgeschlagen markiert und für einen manuellen Neuversuch aufbewahrt. Zustellung mindestens einmal: deduplizieren Sie anhand der id im Payload.
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: the request body exactly as received, before JSON parsing.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const age = Math.abs(Date.now() / 1000 - Number(parts.t))
if (!parts.t || !parts.v1 || age > 300) return false
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest()
const given = Buffer.from(parts.v1, 'hex')
return given.length === expected.length && timingSafeEqual(given, expected)
}API-Referenz
Backend-Endpunkte erwarten einen API-Schlüssel (Authorization: Bearer nb_…). Inbox-Endpunkte erwarten ein Abonnenten-Token, als Bearer-Header oder ?token=.
POST/api/v1/apps/{appId}/notifications
Veröffentlicht an einen Abonnenten (subscriberId) oder bis zu 100 (subscriberIds). Optional: body, category, actionUrl, iconUrl, data (JSON-Objekt bis 4 KB), priority, dedupeKey, actions (bis zu zwei Schaltflächen {label, url}), expiresAt (ISO 8601, innerhalb eines Jahres), template mit variables, sendAt (später zustellen, innerhalb von 90 Tagen). batch: {key, windowSeconds (60–86400), title mit {{ count }}} fasst eine Serie zu einer Benachrichtigung je Abonnent zusammen; nicht mit sendAt. tenant: Ihre Workspace-ID; eine Glocke, deren Token tnt trägt, zeigt die Benachrichtigungen dieses Tenants und ungetaggte.
API-Schlüssel
PATCH · DELETE/api/v1/apps/{appId}/notifications/{id}
PATCH ändert eine gesendete Benachrichtigung direkt (title, body, actionUrl, iconUrl, data, actions; null löscht) – ohne zweite Glocke. DELETE nimmt sie aus dem Posteingang zurück. Offene Glocken aktualisieren sich sofort.
API-Schlüssel
DELETE/api/v1/apps/{appId}/notifications?dedupeKey=…
Nimmt jede mit diesem Dedupe-Schlüssel gesendete Kopie zurück – so wird ein Broadcast widerrufen. Geplante und Dashboard-Sendungen verwenden scheduled:<id>.
API-Schlüssel
POST/api/v1/apps/{appId}/broadcasts
Veröffentlicht an alle Abonnenten der App oder mit topic an alle, die dem Thema folgen. Dieselben optionalen Felder wie beim Veröffentlichen, inklusive template und sendAt. Mit dedupeKey benachrichtigt ein Wiederholungsversuch niemanden doppelt.
API-Schlüssel
GET · DELETE/api/v1/apps/{appId}/scheduled[/{id}]
GET listet geplante Sendungen mit Status und Anzahl der Zustellungen. DELETE /scheduled/{id} bricht eine noch nicht verschickte ab.
API-Schlüssel
GET/api/v1/apps/{appId}/templates
Die im Dashboard bearbeiteten Vorlagen. Veröffentlichen mit template: "key" und variables: { … }; eine fehlende Variable ergibt einen 400 mit ihrem Namen.
API-Schlüssel
GET/api/v1/apps/{appId}/subscribers
Die Abonnenten der App, zuletzt aktive zuerst: limit (1–100), cursor. Abonnenten entstehen beim ersten Senden an sie.
API-Schlüssel
GET · PUT/api/v1/apps/{appId}/subscribers/{externalId}/topics
Liest oder ersetzt die Themen eines Abonnenten ({topics: [...]}, bis zu 100). GET /topics listet alle Themen mit ihrer Anzahl an Folgenden.
API-Schlüssel
GET · PATCH · DELETE/api/v1/apps/{appId}/subscribers/{externalId}
Einen Abonnenten abrufen, aktualisieren (email, name; null löscht) oder mit allen Benachrichtigungen löschen.
API-Schlüssel
GET/api/v1/apps/{appId}/me/feed
Eine Seite des Posteingangs: limit (1–100), cursor, unreadOnly=true, archived=true, snoozed=true, category=a,b (nur diese Kategorien). Abgelaufene Benachrichtigungen fehlen. Liefert ungelesene und ungesehene Zähler.
Abonnenten-Token
GET/api/v1/apps/{appId}/me/stream
Server-Sent Events: ready, notification, read, unread, read-all, seen, archive, archive-read, update, retract, snooze.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/read
Eine als gelesen ({notificationId}), alle als gelesen ({all: true}) oder eine als ungelesen ({notificationId, read: false}) markieren.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/click
Die Person hat auf eine Benachrichtigung reagiert ({notificationId}, optional action: 0 oder 1 für eine Schaltfläche). Markiert sie auch als gelesen; zählt in den Analysen als Klick.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/seen
Alles als gesehen markieren ({all: true}) – beim Öffnen der Glocke aufrufen.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/archive
Eine archivieren ({notificationId}) oder wiederherstellen ({notificationId, archived: false}). Oder alle gelesenen auf einmal: {allRead: true, categories?}.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/snooze
Eine Benachrichtigung zurückstellen ({notificationId, until}: ISO 8601, höchstens 30 Tage). Sie verschwindet sofort aus Feed und Zählern und kommt ungelesen zurück. until: null beendet das vorzeitig.
Abonnenten-Token
POST/api/v1/apps/{appId}/me/delete
Eine eigene Benachrichtigung endgültig löschen ({notificationId}). Archivieren behält sie, dies nicht.
Abonnenten-Token
GET · PATCH/api/v1/apps/{appId}/me/preferences
Auswahl pro Kategorie lesen und setzen ({category, enabled}). Pflichtkategorien erscheinen mit required: true und lassen sich nicht abschalten.
Abonnenten-Token
GET/api/v1/apps/{appId}/me/config
Das im Dashboard festgelegte Theme und die Kategoriebezeichnungen. Das Embed liest sie beim Laden, eine Änderung braucht also kein Deployment.
Abonnenten-Token
Ehrliche Grenzen
- Die Echtzeitverteilung läuft über Redis. Jede Instanz leitet neue Benachrichtigungen über einen gemeinsamen Redis-Kanal weiter, sodass eine irgendwo verbundene Glocke eine irgendwo verarbeitete Veröffentlichung erhält. Ist Redis kurz nicht erreichbar, beliefert jede Instanz weiter ihre eigenen Verbindungen, und verloren geht nichts, weil die Inbox gespeichert und nicht wiedergegeben wird.
- Es gibt kein E-Mail, SMS oder Push. Ganz bewusst. Wenn du Routing über mehrere Kanäle brauchst, ist das hier nicht das richtige Produkt.
- Ein Stream wird fünfzehn Minuten offen gehalten, danach geschlossen, und der Browser verbindet sich mit dem Token neu, das das Element gerade hält. Abonnenten-Tokens gelten standardmäßig ebenfalls fünfzehn Minuten – setzen Sie das token-Attribut daher vor Ablauf neu, sonst aktualisiert sich die Glocke nicht mehr, bis Sie es tun. Das Element löst das Ereignis notify-bell:token-expired aus, wenn sein Token abgelehnt wird, damit Ihre Seite genau dann ein neues holen kann.
- Tokens gelten höchstens 24 Stunden. Ein Abonnenten-Token, dessen Ablauf mehr als einen Tag entfernt liegt, wird abgelehnt – egal, wer es ausgestellt hat. So überlebt ein mit einem später rotierten Schlüssel signiertes Token diesen nicht lange.
- Anfragen sind ratenbegrenzt. Veröffentlichen erlaubt 1.200 Anfragen pro Minute und API-Schlüssel; jeder Abonnent erhält 120 Inbox-Anfragen pro Minute und bis zu 5 offene Streams. Darüber antwortet die API mit 429 und einem Retry-After-Header.