Skip to main content

​
Node.js SDK

The @notifizz/nodejs package is the official server-side SDK for Notifizz. Use it to track events, trigger workflows, generate authentication tokens, and send notifications from your backend.

​
Installation

npm install @notifizz/nodejs

​
NotifizzClient

​
Constructor

const { NotifizzClient } = require("@notifizz/nodejs");

const client = new NotifizzClient(authSecretKey, sdkSecretKey);
ParameterTypeDescription
authSecretKeystringYour Auth Secret Key from the Notifizz dashboard. Used for token generation.
sdkSecretKeystringYour SDK Secret Key from the Notifizz dashboard. Used for API authentication.

​
Methods

​
client.track(props)

Creates a tracking context for an event. Returns a TrackContext that you chain workflows onto. 
await client
  .track({
    eventName: "order_shipped",
    sdkSecretKey: "YOUR_SDK_SECRET_KEY",
    properties: {
      orderId: "ORD-4521",
      carrier: "FedEx",
    },
  })
  .workflow("shipping_notification", [
    { id: "user_42", email: "alice@example.com" },
  ]);
Parameters:
PropertyTypeRequiredDescription
eventNamestringYesThe event slug (must match a workflow in the dashboard).
sdkSecretKeystringYesYour SDK Secret Key.
propertiesobjectYesArbitrary key-value data attached to the event.
Returns: TrackContext — a chainable, promise-like object.

​
TrackContext.workflow(campaignId, recipients)

Attaches a workflow and its recipients to the tracked event. Chainable — you can call it multiple times. 
client
  .track({ eventName: "comment_posted", sdkSecretKey: "...", properties: { ... } })
  .workflow("notify_author", [{ id: "author_1", email: "author@example.com" }])
  .workflow("notify_team", [
    { id: "team_1", email: "lead@example.com" },
    { id: "team_2", email: "manager@example.com" },
  ]);
ParameterTypeRequiredDescription
campaignIdstringYesThe workflow/campaign ID from the dashboard.
recipientsRecipient[]YesArray of recipients for this workflow.
Recipient object:
PropertyTypeRequiredDescription
idstringYesUnique identifier for the recipient.
emailstringYesRecipient’s email address.
...anyNoAdditional custom properties.
Calling .workflow() after the event has been sent (i.e. after the auto-send delay or after awaiting the context) will throw an error.

​
Auto-send behavior

TrackContext behaves like a Promise. The event is automatically sent after a configurable delay (default: 1000ms). You can also await the context to send immediately.
// Auto-sends after 1 second
client.track({ ... }).workflow("campaign_1", [...]);

// Send immediately by awaiting
await client.track({ ... }).workflow("campaign_1", [...]);

​
client.send(request)

Sends a notification directly to the Notification Center, bypassing the event/workflow system. 
const response = await client.send({
  notifId: "notif_template_123",
  properties: {
    recipients: [{ id: "user_42", email: "alice@example.com" }],
    title: "Your report is ready",
    message: "Click to download your monthly report.",
  },
});
PropertyTypeRequiredDescription
notifIdstringYesThe notification template ID.
propertiesobjectYesMust include recipients array. Can include any additional data.
Returns: Promise<any> — the API response data. Throws: On network or API errors.

​
client.generateHashedToken(userId)

Generates an HMAC token for backend token authentication. Pass this token to your frontend so the widget can authenticate securely. 
const token = client.generateHashedToken("user_42");
// Return this to your frontend via an API endpoint
ParameterTypeDescription
userIdstringThe user’s unique identifier.
Returns: string — an SHA-256 HMAC hash.

​
client.config(options)

Configures SDK behavior. Options are merged with defaults. 
client.config({
  autoSendDelayMs: 2000,
  baseUrl: "https://eu.api.notifizz.com/v1",
});
OptionTypeDefaultDescription
autoSendDelayMsnumber1000Delay in milliseconds before auto-sending tracked events.
baseUrlstring"https://eu.api.notifizz.com/v1"Base URL for the Notifizz API.

​
Types reference

​
TrackProps

Passed to client.track().
PropertyTypeRequiredDescription
eventNamestringYesThe event slug matching a workflow in the dashboard.
sdkSecretKeystringYesYour SDK Secret Key.
propertiesobjectYesArbitrary key-value data attached to the event.

​
Recipient

Each entry in the recipients array passed to .workflow().
PropertyTypeRequiredDescription
idstringYesUnique identifier for the recipient.
emailstringYesRecipient’s email address.
custom keysanyNoAny additional properties for use in templates.

​
NotifizzOptions

Passed to client.config().
PropertyTypeDefaultDescription
autoSendDelayMsnumber1000Delay in ms before auto-sending tracked events.
baseUrlstring"https://eu.api.notifizz.com/v1"Base URL for the Notifizz API.

​
EventProperties

Passed to client.send().
PropertyTypeRequiredDescription
notifIdstringYesThe notification template ID.
propertiesobjectYesMust include a recipients array. Can include any additional data.
properties.recipientsRecipient[]YesArray of recipients for the notification.
The TrackProps and EventProperties tables mirror the parameters described in the methods above. They are provided here as a quick reference for TypeScript users.

​
Error handling

The SDK throws errors on network failures and API errors. Wrap calls in try/catch: 
try {
  await client
    .track({
      eventName: "payment_received",
      sdkSecretKey: "YOUR_SDK_SECRET_KEY",
      properties: { amount: 99.99 },
    })
    .workflow("payment_confirmation", [
      { id: "user_42", email: "alice@example.com" },
    ]);
} catch (error) {
  console.error("Failed to send notification:", error.message);
}

​
Next steps

Backend quickstart

Get started with a complete example in under 5 minutes.

Frontend SDKs

Set up the widget to display the notifications you’re sending.