GuidesNotifications
Backend Sending Patterns
Publish notifications from backend domain events with reliable delivery, stable metadata, and actionable CTAs.
Backend Sending Patterns
Notifications should be emitted from backend business events, not frontend click handlers.
Producer design pattern
- Domain event occurs (
api_key_revoked,endpoint_disabled,invite_accepted). - Producer resolves target scope (
user_id,organization_id,workspace_id). - Producer builds template (
title,body,severity,ctas,metadata, expiry). - Producer publishes via backend SDK.
Backend JS SDK example
import { WachtClient } from "@wacht/backend";
const client = new WachtClient({ apiKey: process.env.WACHT_BACKEND_API_KEY! });
await client.notifications.createNotification({
user_id: "1234567890123456789",
title: "Webhook endpoint disabled",
body: "Endpoint https://example.com/hooks was auto-disabled after repeated failures.",
severity: "warning",
ctas: [{ label: "Review endpoint", url: "https://app.example.com/settings/webhooks/endpoints" }],
metadata: {
endpoint_id: "ep_987",
incident_id: "inc_456",
source: "webhook-delivery-worker",
},
expires_hours: 24,
});Raw HTTP fallback
await fetch(`${process.env.WACHT_BACKEND_API_URL}/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 was auto-disabled after repeated failures.",
severity: "warning",
ctas: [{ label: "Review endpoint", url: "https://app.example.com/settings/webhooks/endpoints" }],
metadata: { endpoint_id: "ep_987", incident_id: "inc_456" },
expires_hours: 24,
}),
});Reliability rules
- Never block critical transactional paths on notification publish success.
- Retry with bounded policy and idempotency guard in producer layer.
- Keep
metadatakeys stable and documented for UI/analytics consumers. - Deduplicate noisy events by window when appropriate.
Template quality rules
- Title states the event, not just “Something happened”.
- Body includes affected entity and impact.
- CTA points directly to remediation screen.
- Severity matches urgency and expected user action.
Validation checklist
- Scope routing (
user/org/workspace) matches business policy. - CTA destination and permissions are valid.
- Expiry applied to transient notifications.
- Producer retries and dedupe are tested under failure.