Trigger workflows to topics

Once you've created your topics and added subscribers, you're ready to send them notifications. Triggering a workflow to a topic is the core mechanism for broadcasting a message to a large audience with a single API call.

When you trigger a workflow using a topic key, Novu performs a fan-out: it identifies all subscribers within that topic and creates an individual workflow run for each one.

This process is handled entirely by Novu, saving you from writing complex loops or sending thousands of separate API requests. The trigger syntax is the same as for individual subscribers; you only need to specify the type as Topic in the to field.

Trigger to a single topic

The most common use case is broadcasting a notification to every subscriber within a single topic. This is ideal for product announcements, incident updates, or other targeted mass communications.

To trigger a workflow to a topic, use the to field with type: "Topic" and the corresponding topicKey.

import { Novu } from "@novu/api"
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.trigger({
  to: { type: "Topic", topicKey: "topic_key" },
  workflowId: "workflow_identifier",
});

Trigger to multiple topics

You can also broadcast a notification to several topics at once by passing an array in the to field. This is useful when your audience spans multiple groups, such as notifying both "paying-customers" and "beta-testers" about an important update.

Novu automatically handles de-duplication, so if a subscriber belongs to more than one of the specified topics, they will only receive the notification once.

import { Novu } from "@novu/api"
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.trigger({
  to: [
    { type: "Topic", topicKey: "topic_key_1" }, 
    { type: "Topic", topicKey: "topic_key_2" }
  ],
  workflowId: "workflow_identifier",
});

Exclude an actor for a notification

When a workflow is triggered to a topic, notification is sent to all subscribers present in the topic. However, you can exclude a specific subscriber (for example, the user who performed the action) by passing their subscriberId in the actor field.

You can achieve this by passing the subscriberId of the initiator in the actor field. Novu will then exclude this subscriber from that specific trigger event.

import { Novu } from "@novu/api"
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.trigger({
  to: [{ type: "Topic", topicKey: "topic_key_1" }],
  workflowId: "workflow_identifier",
  actor: "actor_subscriber_Id"
});