Skip to main content

​
Backend Sending Patterns

Your backend should send notifications from business events, not UI clicks.

​
Backend endpoint and schema

From your backend API specs, POST /notifications accepts core fields like:
  • user_id
  • title
  • body
  • severity
  • ctas
  • metadata
  • expiry controls

​
Practical domain patterns

​
Security pattern

  • password changed
  • mfa enabled/disabled
  • unknown sign-in detected

​
Collaboration pattern

  • invite accepted
  • role changed
  • workspace membership updated

​
Operations pattern

  • webhook endpoint disabled
  • API key revoked/rotated
  • automation failed and needs attention

​
Example

​
Option A: Direct HTTP call

await fetch("https://api.wacht.dev/notifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WACHT_BACKEND_API_KEY!}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "1234567890123456789",
    title: "Webhook endpoint disabled",
    body: "Endpoint https://example.com/hooks returned repeated failures and was disabled.",
    severity: "warning",
    action_url: "https://app.example.com/settings/webhooks/endpoints",
    action_label: "Review endpoint",
    metadata: { endpoint_id: "ep_987" },
    expires_hours: 24,
  }),
});

​
Option B: Backend SDK (@wacht/backend)

import { WachtClient } from "@wacht/backend";

const client = new WachtClient({
  apiKey: process.env.WACHT_BACKEND_API_KEY!,
  baseUrl: "https://api.wacht.dev",
});

await client.notifications.createNotification({
  user_id: "1234567890123456789",
  title: "Webhook endpoint disabled",
  body: "Endpoint https://example.com/hooks returned repeated failures and was disabled.",
  severity: "warning",
  ctas: [{ label: "Review endpoint", url: "https://app.example.com/settings/webhooks/endpoints" }],
  metadata: { endpoint_id: "ep_987" },
  expires_in_hours: 24,
});

​
Backend reliability rules

  1. Do not block critical domain transaction on notification send failures.
  2. Retry publish with bounded retry policy.
  3. Keep metadata stable and parsable.
  4. Avoid sending duplicate notifications for same event window.
  1. Backend API Notifications Reference
  2. Frontend API Notifications Reference
  3. React Router useNotifications
  4. React Router useNotificationStream

​
Go-live checklist

  1. Scope and severity conventions are documented.
  2. Inbox read/archive/star flows are tested.
  3. Realtime reconnection behavior is verified.
  4. Noisy template monitoring is in place.
  5. Expiry strategy is applied for stale notifications.