v1.0 · open source

Notification
infrastructure
for your app

A self-hosted notification backend — async queue, real-time delivery via Socket.io, offline sync, and API key auth. Ships in one deploy.

Open Dashboard Integration guide

<50ms delivery latency

5× auto-retry

2-layer idempotency

100% free forever

notify.js

// send from your backend
const res = await fetch('https://YOUR_API/api/notify', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey nx_...',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    recipientId: 'user_123',
    type:        'like',
    payload:     { message: 'Alice liked your post' },
  }),
})
// → 202 { status: 'queued', jobId: 'bull:...' }
// worker saves to MongoDB, pushes via Socket.io

Architecture

How a notification travels

API server and worker are separate Node.js processes. Redis is the only bridge — no shared memory, no coupling.

Your App

POST /api/notify with recipient, type, payload

API Server

Validates, deduplicates via Redis SETNX, returns 202

Dispatch

setImmediate — prefs check, Mongo save, in-process emit

Browser

Socket.io delivers in real time. Offline users sync on reconnect.

What's included

Production patterns, out of the box

Built around the patterns that actually matter when notifications fail in production.

In-process async dispatch

POST /api/notify returns 202 after a single Redis SET NX. Dispatch runs on the next tick via setImmediate — no queue, no broker, no separate worker process to keep awake.

Real-time via Socket.io

Dispatch checks io.sockets.adapter.rooms.get(userId) for presence and calls io.to(userId).emit() directly. No Pub/Sub bridge, no extra Redis hops.

Two-layer idempotency

API gate uses Redis SETNX with 24-hour TTL. Worker falls back to a MongoDB sparse unique index. Sending the same request twice is safe — the second returns 409 with no side effects.

Offline sync on reconnect

Worker checks online:{userId} in Redis. Offline users accumulate notifications with delivered: false. Socket.io flushes them the moment the user reconnects.

Integration

Add notifications in three steps

No SDK required. Standard HTTP and Socket.io.

Generate an API key

Open the dashboard, sign in, and request a key under Settings. Keys are prefixed nx_ and stored as SHA-256 hashes — shown once at creation.

Call POST /api/notify

Send your key in the Authorization: ApiKey header. Include an Idempotency-Key to prevent duplicate delivery — the queue handles retries and backoff automatically.

Listen via Socket.io

Connect with a JWT from POST /api/auth/token. Subscribe to the notification event. Missed notifications while offline are replayed on reconnect.

Notificationinfrastructurefor your app