Skip to main content

​
Notifizz backend quickstart

Send your first event from a backend in under five minutes. The SDK call is one line; Notifizz resolves the campaign, builds the recipients, and dispatches the notification — all server-side.

​
TL;DR

  • Install @notifizz/nodejs (or the Java / PHP SDK).
  • Construct the client with your auth secret + SDK secret.
  • Call await client.track(eventName, properties, { idempotencyKey }).
  • The backend acks within milliseconds; the campaign runs asynchronously.
Get your Auth Secret Key and SDK Secret Key from the Notifizz dashboard under your environment settings. Keys are scoped per environment (dev / prod) — see keys and environments.

​
1. Install the SDK

npm install @notifizz/nodejs

yarn add @notifizz/nodejs

pnpm add @notifizz/nodejs
Java and PHP have the same shape — see Java or PHP for their install snippets. The rest of this quickstart uses Node.

​
2. Initialise the client

import { NotifizzClient } from "@notifizz/nodejs";

const client = new NotifizzClient(
  process.env.NOTIFIZZ_AUTH_SECRET_KEY,
  process.env.NOTIFIZZ_SDK_SECRET_KEY,
);
The third constructor argument (webhookSigningSecret) is required only if you mount enrichers. Skip it for the quickstart.

​
3. Track your first event

Match the eventName to an event you registered in the dashboard (or one tied to an active campaign): 
await client.track("user.signed_up", {
  userId: "u_42",
  email: "alice@example.com",
  plan: "pro",
});
That’s it. client.track() posts to POST /v1/events/track, and Notifizz takes over: the event is queued, one workflow instance is created per matching campaign, the AI orchestrator builds the recipient list (calling enrichers to fetch any live data the event didn’t carry), and the notification ships through every channel the campaign configures.
Notice what’s not in the call: no campaign ID, no recipient list, no template. Routing is server-side — that’s the whole point. New campaigns ship without redeploying your code.

​
4. Use idempotency for retried jobs

If the same logical emit may run twice (queue retries, scheduler, retry middleware), set an explicit idempotency key derived from your domain: 
await client.track(
  "order.shipped",
  { orderId: "ORD-4521", userId: "u_42" },
  { idempotencyKey: `order-shipped:ORD-4521` },
);
A retried emit with the same key produces the same outcome — the backend responds { duplicate: true, idempotencyKey } and does not re-enqueue the campaign.

​
5. Watch retries

The SDK retries transient failures twice (1s, then 2s) before bubbling the error: 
try {
  await client.track("order.shipped", { orderId, userId });
} catch (e) {
  // After 3 total attempts, the original axios error rethrows here.
  logger.error({ err: e, orderId }, "notifizz track failed");
  throw e;
}
Don’t fire-and-forget without logging — silent network failures hide real outages.

​
6. (Optional) Generate a widget auth token

If your frontend uses backend-token authentication, generate a per-user token from the same client: 
const token = client.generateHashedToken("u_42");
// Return this token to your frontend through your own API.
Pass it as token (along with userId + userEmail) when initialising the widget — see frontend quickstart.

​
What just happened

1

Event accepted

POST /v1/events/track returned 200 and the SDK resolved its promise.
2

Campaigns matched

Notifizz looked up campaigns wired to user.signed_up (or order.shipped) in your environment.
3

Workflow instance created

One instance per matching campaign. Each instance has its own recipient list, computed by the orchestrator from your event properties (and any enricher the campaign declares).
4

Channels dispatched

The notification queue (the dispatcher) calls each channel — Notification Center widget, email — with the resolved content.
Open the Notification Center widget for u_42 (frontend quickstart) and the message appears in real time. No refresh needed.
Want a measurable programme — fast? Notifizz Certified Partners are vetted experts who lead complete notification engagements end to end: tagging plan, enrichers wired, AI/MCP configured, first campaigns live, and your team trained to own it. The shortest path from your first event to a programme that pays back. Find a partner →

​
Troubleshooting

The sdkSecretKey is wrong or scoped to a different environment. Each environment (dev, prod, …) has its own pair — copy the right one from the dashboard. Don’t share keys across environments.
Three checks: (1) is there a campaign in the dashboard listening on this exact eventName and is its status Live (or Dev for dev environments)?; (2) does the campaign’s recipient logic resolve from the properties you sent (e.g. userId present)?; (3) is the user’s widget authenticated with the same userId?
No — that’s the success path for an idempotent retry. The backend has already processed an event with the same idempotencyKey. Your code does not need to do anything.
track() is async and the SDK retries failures with 1s + 2s delays — a degraded backend can stall your handler for up to ~3s. Either fire-and-log (track().catch(...) without await) or push the emit onto a queue you control.
Yes when the same logical emit may run twice. Use a deterministic key (order-shipped:${orderId}), not crypto.randomUUID() — random keys defeat the dedupe by producing a new key per attempt.

​
See also

Work with a Certified Partner

Skip the discovery-as-you-go path. Vetted experts run the project end to end.

Frontend quickstart

Set up the widget so users see the notifications.

Node.js SDK reference

Full API: enrichers, error classes, retry behaviour.

How Notifizz works

The event-driven pipeline, end to end.