Trigger Notification

Send notifications by triggering Novu workflows. Supports single, bulk, broadcast, and topic-based delivery.

SDK Setup

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

Single Trigger

Send a notification to one subscriber:

const result = await novu.trigger({
  workflowId: "welcome-email",
  to: "subscriber-123",
  payload: {
    userName: "Jane",
    activationLink: "https://app.example.com/activate",
  },
});

Trigger with Inline Subscriber Creation

If the subscriber doesn't exist yet, provide the full object — Novu upserts the subscriber:

const result = await novu.trigger({
  workflowId: "welcome-email",
  to: {
    subscriberId: "user-456",
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Doe",
  },
  payload: { userName: "Jane" },
});

Trigger with Transaction ID

Use custom transactionId for idempotency:

const result = await novu.trigger({
  workflowId: "order-update",
  to: "subscriber-123",
  payload: { orderId: "order-789" },
  transactionId: "unique-tx-id-abc",
});

Bulk Trigger

Send up to 100 events in a single request:

const result = await novu.triggerBulk({
  events: [
    {
      workflowId: "welcome-email",
      to: "subscriber-1",
      payload: { userName: "Alice" },
    },
    {
      workflowId: "welcome-email",
      to: "subscriber-2",
      payload: { userName: "Bob" },
    },
  ],
});

Broadcast

Send to all subscribers in the environment:

const result = await novu.triggerBroadcast({
  // here name field is for workflowId
  name: "system-announcement",
  payload: {
    message: "Scheduled maintenance at 2am UTC",
  },
});

Topic-Based Trigger

Send to all subscribers in a topic:

const result = await novu.trigger({
  workflowId: "project-update",
  to: [{
    type: "Topic",
    topicKey: "project-alpha-watchers",
  }],
  payload: { update: "New release deployed" },
});

Cancel a Trigger

Cancel delayed or digested notifications using the transactionId:

await novu.cancel("unique-tx-id-abc");

Trigger Parameters

Parameter	Required	Description
`workflowId`	Yes	The workflow identifier (not display name)
`to`	Yes	Subscriber ID (string), subscriber object, or topic target
`payload`	No	Data passed to the workflow, validated against `payloadSchema`
`overrides`	No	Provider-specific overrides per channel
`transactionId`	No	Unique ID for idempotency and cancellation
`actor`	No	Subscriber ID or object representing who triggered the action
`context`	No	Key-value pairs for multi-tenancy / organizational context

Overrides

Override provider-specific settings per trigger:

const result = await novu.trigger({
  workflowId: "alert",
  to: "subscriber-123",
  payload: { message: "Server down" },
  overrides: {
    "providers": {
      "sendgrid": {
        from: "alerts@example.com",
        cc: ["user1@example.com", "user2@example.com"],
        replyTo: "support@example.com",
      }
    }
  },
});

Common Pitfalls

workflowId is the identifier, not the display name — use the identifier you set when defining the workflow, not its human-readable name. Novu creates workflowId automatically if not provided
Subscriber upsert — triggering to a non-existent subscriberId or subscriber object string will create the subscriber with that subscriberId.
Bulk trigger limit is 100 events — chunk larger batches into groups of 100.
transactionId is required for cancellation — you cannot cancel a trigger without it. Either provide custom transactionId or store novu generated transactionId if usecase is to cancel the workflow run (trigger event) later.
Payload is validated against the workflow's payloadSchema — if the workflow defines a schema, the trigger will fail if the payload doesn't match.

novu-trigger-notification