Trigger Workflow

Triggering a workflow starts the execution of a notification pipeline in Novu. A workflow is triggered when an event is sent to Novu. When a workflow is triggered, Novu resolves the target subscribers, evaluates workflow logic, and executes each configured step to deliver notifications across the selected channels. Trigger requests can include payload data, context, or target a topic, allowing you to control both who receives the notification and what data is available during execution.

Test with a real subscriber

A real subscriber already exists in the same environment, with the subscriberId your app uses and the channel fields the workflow needs, such as email.

Create the subscriber on the Subscribers page, or pass their profile on the trigger.
Open the workflow and click Test workflow.
Select that subscriber, fill the payload, and send.
Open the Activity Feed and filter by that subscriber ID.

The demo email integration only delivers to the email address on your Novu account. To reach a subscriber’s own address, connect your email provider and store that address on the subscriber. An Inbox test needs the <Inbox /> component initialized with the same application identifier and subscriberId.

Integrate a workflow trigger in my app

Open in Cursor

Trigger Event API

Trigger a workflow from your backend by sending an event to the Novu API. An event represents an action in your system, for example, an order created or a comment added, and is mapped to a workflow using the workflow’s trigger identifier. Call POST https://api.novu.co/v1/events/trigger with the environment secret key. Never put that key in frontend code. The REST field for the workflow identifier is name. The server SDKs call it workflowId. A workflow must be published before a Production trigger can run it. If the subscriber does not exist yet, passing to as an object creates them on that trigger. When you trigger an event, you specify:

The workflow to execute.
The subscriber (or subscribers) the notification is intended for.
The payload data used to personalize notification content.

At a minimum, triggering a workflow requires the workflow trigger identifier and a subscriber identifier.

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

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: [{ subscriberId: "string" }],
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to={"subscriber_id": "string"},
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "string",
    }),
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\SubscriberPayloadDto(subscriberId: 'string'),
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateStr("string"),
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of("string"))
        .build())
    .call();

curl -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflow_identifier",
    "to": {
        "subscriberId": "string"
    }
}'

For full request options and response details, see the Trigger Event API reference.

Once the event is received, Novu executes the workflow, evaluates step conditions, resolves variables, and delivers notifications across the configured channels. From here, you can extend event triggering by attaching context data, overriding the workflow-assigned agent, or targeting multiple subscribers using topics.

Override the assigned agent

If the workflow has an agent assigned in Configure workflow, that agent is the default for every trigger. Pass agentId on the trigger to change that for a single execution:

`agentId`	Behavior
Omitted	Use the workflow-assigned agent
Public agent identifier	Route this execution through that agent
`null`	Disable agent routing for this execution

agentId is the public agent slug, not the Mongo _id. See Workflow-assigned agents.

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

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: [{ subscriberId: "string" }],
  agentId: "support-agent",
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to={"subscriber_id": "string"},
        agent_id="support-agent",
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

agentID := "support-agent"
res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "string",
    }),
    AgentID: &agentID,
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\SubscriberPayloadDto(subscriberId: 'string'),
        agentId: 'support-agent',
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateStr("string"),
    AgentId = "support-agent",
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of("string"))
        .agentId("support-agent")
        .build())
    .call();

curl -X POST "https://api.novu.co/v1/events/trigger" \
  -H "Authorization: ApiKey <NOVU_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -H 'Accept: application/json' \
  -d '{
    "name": "workflow_identifier",
    "to": [{ "subscriberId": "string" }],
    "agentId": "support-agent"
  }'

To skip agent routing for one run while leaving the workflow assignment in place, pass agentId: null.

Trigger a workflow with context

You can attach context data when triggering a workflow using the Event API. Context can be referenced from existing contexts created in the Novu dashboard by providing the context type and identifier or defined inline at trigger time. Any context passed with the event is available to all downstream steps and channel templates during workflow execution. When you pass a rich context object with a data field, Novu upserts the stored context data if the context already exists - similar to subscriber fields on the to object. Passing only a string identifier references the context without changing stored data. Context data is passed using the context object in the trigger request.

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

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: [{ subscriberId: "string" }],
  context: {
    context_type: "context_identifier",
    region: "us-east-1",
    app: "dashboard"
  }
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to={"subscriber_id": "string"},
        context={
            "context_type": "context_identifier",
            "region": "us-east-1",
            "app": "dashboard",
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "string",
    }),
    Context: map[string]any{
        "context_type": "context_identifier",
        "region":       "us-east-1",
        "app":          "dashboard",
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\SubscriberPayloadDto(subscriberId: 'string'),
        context: [
            'context_type' => 'context_identifier',
            'region' => 'us-east-1',
            'app' => 'dashboard',
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateStr("string"),
    Context = new Dictionary<string, object>() {
        { "context_type", "context_identifier" },
        { "region", "us-east-1" },
        { "app", "dashboard" },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of("string"))
        .context(Map.ofEntries(
            Map.entry("context_type", TriggerEventRequestDtoContextUnion.of("context_identifier")),
            Map.entry("region", TriggerEventRequestDtoContextUnion.of("us-east-1")),
            Map.entry("app", TriggerEventRequestDtoContextUnion.of("dashboard"))))
        .build())
    .call();

curl -X POST "https://api.novu.co/v1/events/trigger" \
  -H "Authorization: ApiKey <NOVU_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -H 'Accept: application/json' \
  -d '{
    "name": "workflow_identifier",
    "to": [{ "subscriberId": "string" }],
    "context": {
      "context_type": "context_identifier",
      "region": "us-east-1",
      "app": "dashboard"
    }
  }'

To learn how contexts work and how to manage them, see the Context documentation.

Trigger a workflow to a topic

Once you’ve created topics and added subscribers, you can trigger workflows to those subscribers in bulk. Triggering a workflow to a topic is Novu’s primary mechanism for broadcasting notifications to large audiences with a single API call. When you trigger a workflow using a topic key, Novu performs a fan-out: it resolves all subscribers in the topic and executes the workflow independently for each subscriber.

To learn how to create and manage Topics, see the Topics API reference.

Trigger to a single topic

The most common use case is sending a notification to all subscribers within a single topic. This is suitable for announcements, incident updates, or targeted broadcasts. To trigger a workflow to a topic, set the to field with type: "Topic" and provide the corresponding topicKey.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: { type: "Topic", topicKey: "topic_key" },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to={"type": "Topic", "topic_key": "topic_key"},
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToTopicPayloadDto(components.TopicPayloadDto{
        Type:     components.TriggerRecipientsTypeEnumTopic,
        TopicKey: "topic_key",
    }),
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\TopicPayloadDto(
            topicKey: 'topic_key',
            type: Components\TriggerRecipientsTypeEnum::Topic,
        ),
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateTopicPayloadDto(new TopicPayloadDto() {
        Type = TriggerRecipientsTypeEnum.Topic,
        TopicKey = "topic_key",
    }),
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of(TopicPayloadDto.builder()
            .type(TriggerRecipientsTypeEnum.TOPIC)
            .topicKey("topic_key")
            .build()))
        .build())
    .call();

curl -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflow_identifier",
    "to": {
        "type": "Topic",
        "topicKey": "topic_key"
    }
}'

Trigger to multiple topics

You can broadcast a notification to multiple topics by passing an array to the to field. This is useful when your audience spans multiple groups, such as notifying both paying-customers and beta-testers. Novu automatically de-duplicates subscribers. If a subscriber belongs to more than one of the specified topics, they will receive the notification only once.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: [
    { type: "Topic", topicKey: "topic_key_1" }, 
    { type: "Topic", topicKey: "topic_key_2" }
  ]
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to=[
            {"type": "Topic", "topic_key": "topic_key_1"},
            {"type": "Topic", "topic_key": "topic_key_2"},
        ],
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToArrayOfTo1([]components.To1{
        components.CreateTo1TopicPayloadDto(components.TopicPayloadDto{
            Type:     components.TriggerRecipientsTypeEnumTopic,
            TopicKey: "topic_key_1",
        }),
        components.CreateTo1TopicPayloadDto(components.TopicPayloadDto{
            Type:     components.TriggerRecipientsTypeEnumTopic,
            TopicKey: "topic_key_2",
        }),
    }),
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: [
            new Components\TopicPayloadDto(
                topicKey: 'topic_key_1',
                type: Components\TriggerRecipientsTypeEnum::Topic,
            ),
            new Components\TopicPayloadDto(
                topicKey: 'topic_key_2',
                type: Components\TriggerRecipientsTypeEnum::Topic,
            ),
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateArrayOfTo1(new List<To1> {
        To1.CreateTopicPayloadDto(new TopicPayloadDto() {
            Type = TriggerRecipientsTypeEnum.Topic,
            TopicKey = "topic_key_1",
        }),
        To1.CreateTopicPayloadDto(new TopicPayloadDto() {
            Type = TriggerRecipientsTypeEnum.Topic,
            TopicKey = "topic_key_2",
        }),
    }),
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of(List.of(
            To1.of(TopicPayloadDto.builder()
                .type(TriggerRecipientsTypeEnum.TOPIC)
                .topicKey("topic_key_1")
                .build()),
            To1.of(TopicPayloadDto.builder()
                .type(TriggerRecipientsTypeEnum.TOPIC)
                .topicKey("topic_key_2")
                .build()))))
        .build())
    .call();

curl -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflow_identifier",
    "to": [
      {
          "type": "Topic",
          "topicKey": "topic_key_1"
      },
      {
          "type": "Topic",
          "topicKey": "topic_key_2"
      }
    ]
}'

Exclude a subscriber from a topic trigger

When a workflow is triggered to a topic, all subscribers in that topic are included by default. You can exclude specific subscribers from receiving the notification for that trigger by using the exclude field. This exclusion applies only to the current trigger request and does not modify the topic membership.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
  workflowId: "workflow_identifier",
  to: [{ type: "Topic", topicKey: "topic_key", exclude: ["subscriber-id"] }],
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflow_identifier",
        to=[{
            "type": "Topic",
            "topic_key": "topic_key",
            "exclude": ["subscriber-id"],
        }],
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflow_identifier",
    To: components.CreateToArrayOfTo1([]components.To1{
        components.CreateTo1TopicPayloadDto(components.TopicPayloadDto{
            Type:     components.TriggerRecipientsTypeEnumTopic,
            TopicKey: "topic_key",
            Exclude:  []string{"subscriber-id"},
        }),
    }),
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: [
            new Components\TopicPayloadDto(
                topicKey: 'topic_key',
                type: Components\TriggerRecipientsTypeEnum::Topic,
                exclude: ['subscriber-id'],
            ),
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflow_identifier",
    To = To.CreateArrayOfTo1(new List<To1> {
        To1.CreateTopicPayloadDto(new TopicPayloadDto() {
            Type = TriggerRecipientsTypeEnum.Topic,
            TopicKey = "topic_key",
            Exclude = new List<string> { "subscriber-id" },
        }),
    }),
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflow_identifier")
        .to(To2.of(List.of(
            To1.of(TopicPayloadDto.builder()
                .type(TriggerRecipientsTypeEnum.TOPIC)
                .topicKey("topic_key")
                .exclude(List.of("subscriber-id"))
                .build()))))
        .build())
    .call();

curl -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflow_identifier",
    "to": [
      {
          "type": "Topic",
          "topicKey": "topic_key",
          "exclude": ["subscriber-id"]
      }
    ]
}'

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Trigger Workflow

Test with a real subscriber

Trigger Event API

Override the assigned agent

Trigger a workflow with context

Trigger a workflow to a topic

Trigger to a single topic

Trigger to multiple topics

Exclude a subscriber from a topic trigger

​Test with a real subscriber

​Trigger Event API

​Override the assigned agent

​Trigger a workflow with context

​Trigger a workflow to a topic

​Trigger to a single topic

​Trigger to multiple topics

​Exclude a subscriber from a topic trigger

Test with a real subscriber

Trigger Event API

Override the assigned agent

Trigger a workflow with context

Trigger a workflow to a topic

Trigger to a single topic

Trigger to multiple topics

Exclude a subscriber from a topic trigger