Novu 触发通知(Trigger Notification)完整指南:单次、批量、广播、主题触发与取消

原创2026-09-09 22:31:311,930 阅读
文章标签:后端消息路由工作流自动化前端WebSocketMCP 服务微服务

Novu 触发通知(Trigger Notification)完整指南:单次、批量、广播、主题触发与取消

本文以 Novu 官方技能文档 SKILL.md 及其参考手册为核心,系统讲解如何通过 @novu/api SDK 触发 Novu 工作流,向邮件、短信、Push、聊天与应用内(in-app)等渠道发送通知。读完本文,你将掌握单次触发、内联创建订阅者、批量触发(上限 100 事件)、向全部订阅者广播、基于主题(Topic)定向发送,以及通过 transactionId 实现幂等与取消通知的完整实战方案,并了解这些能力在仓库源码中的底层实现。

使用前提与 SDK 安装

Node.js / TypeScript

@novu/api 是 Novu 官方 TypeScript SDK,在仓库中对应 libs/internal-sdk(该目录下代码由 Speakeasy 基于 OpenAPI 规范自动生成,文件头部标注 "DO NOT EDIT")。安装方式:

npm install @novu/api
# 或
pnpm add @novu/api
# 或
yarn add @novu/api

环境变量

在 .env 中配置服务端密钥:

NOVU_SECRET_KEY=your-secret-key-here

该密钥是服务端专用 API Key,可在 Novu Dashboard 的 API Keys 页面获取。在技能文档的前置元数据(frontmatter)中,NOVU_SECRET_KEY 被声明为必填的 secret 类型输入,说明所有触发操作都依赖它完成服务端鉴权。

初始化 SDK

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

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

Python

pip install novu-py
import novu_py
from novu_py import Novu

with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

cURL(REST API 直调)

所有 API 请求都需要携带 Authorization 头:

curl -X POST https://api.novu.co/v1/events/trigger \
  -H "Authorization: ApiKey YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-id",
    "to": "subscriber-id",
    "payload": {}
  }'

注意:在 REST API 中,触发字段名为 name(而非 workflowId)。SDK 会自动把 workflowId 映射为 REST 请求体中的 name——这一点在 DTO 源码中有直接体现:trigger-event-request.dto.ts 中字段定义为 name,同时通过 @SdkApiProperty(..., { nameOverride: 'workflowId' }) 让 SDK 层以 workflowId 对外暴露。

核心概念:workflowId、to 与触发路径

一次触发本质上是一个 POST 请求,由 API 侧 events.controller.ts 的 POST /v1/events/trigger 端点承接(@SdkMethodName('trigger'))。它背后由 ParseEventRequestMulticastCommand 解析请求并进入工作流编排流程。

触发时两个必填概念:

  • workflowId:工作流标识符,是你在定义工作流时设置的 identifier,不是人类可读的显示名称。若未显式提供,Novu 会自动生成。
  • to:收件人,可以是订阅者 ID 字符串、订阅者对象、主题(Topic)目标,或它们的数组。源码中 to 字段被定义为 TriggerRecipientsPayload,其 oneOf 组合覆盖了字符串、订阅者对象与主题对象三种形态(见 trigger-event-request.dto.ts),且单次触发最多支持 100 个收件人。

单次触发(Single Trigger)

向单个订阅者发送通知是最基础的用法:

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

payload 会传入工作流用于渲染模板内容,同时可用于步骤过滤与路由规则;该数据也会在通过 API 拉取通知流时可用于展示部分 UI。

触发时内联创建/更新订阅者(Upsert)

如果订阅者尚不存在,传入完整对象即可——Novu 会自动 upsert(存在则更新、不存在则创建)该订阅者:

const result = await novu.trigger({
  workflowId: "welcome-email",
  to: {
    subscriberId: "user-456",
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Doe",
    phone: "+15551234567",
    avatar: "https://example.com/avatars/jane.jpg",
    locale: "en-US",
    data: {
      plan: "pro",
      signupSource: "landing-page",
    },
  },
  payload: { userName: "Jane" },
});

data 字段用于携带订阅者的自定义属性。若只是以字符串形式传入一个不存在的 subscriberId,Novu 同样会以该 ID 创建订阅者。

指定 Actor(动作发起人)

actor 用于标明“是谁触发了这个动作”,其信息(如头像)可在模板中使用:

const result = await novu.trigger({
  workflowId: "comment-notification",
  to: "post-author-123",
  payload: {
    commentText: "Great post!",
    postTitle: "Getting Started with Novu",
  },
  actor: "commenter-456",
});

源码中 actor 同样支持字符串或订阅者对象,若传入新对象会同步创建对应订阅者(见 trigger-event-request.dto.ts)。

使用自定义 transactionId 实现幂等

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

transactionId 是本次触发事件的唯一标识,用于幂等去重与后续取消。若同一 transactionId 再次被发送,触发会被忽略(保留期取决于计费套餐),详见 events.controller.ts 的接口描述。

渠道级 Overrides(覆盖 Provider 配置)

overrides 可按渠道 Provider 覆盖特定配置,例如邮件发件人、抄送与回复地址:

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",
      }
    }
  },
});

源码中 overrides 的类型为 TriggerOverrides,其中 providers 以 ProvidersIdEnum 为键、以 provider 特定配置对象为值,还支持 layoutId 覆盖步骤布局等高级能力(见 trigger-event-request.dto.ts)。注意部分旧式字段(如顶层 email/sms/push/chat 覆盖)在源码中已被标记为 deprecated: true,推荐统一使用 overrides 结构。

多租户 Context(组织上下文)

context 用于多租户场景下传递组织级上下文:

const result = await novu.trigger({
  workflowId: "invoice-created",
  to: "user-123",
  payload: { invoiceId: "INV-001" },
  context: {
    organizationId: "org-acme",
  },
});

源码中 context 通过 @IsValidContextPayload({ maxCount: 5 }) 校验,即单次触发最多携带 5 个键值对(见 trigger-event-request.dto.ts)。此外,同文件还提供了 tenant 字段用于指定租户上下文(已存在的租户会被更新)。

批量触发(Bulk Trigger)

当需要在一次请求中发送多条独立事件时,使用 triggerBulk,单次请求最多 100 个事件:

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

REST 对应的端点是 POST /v1/events/trigger/bulk(见 events.controller.ts,@SdkMethodName('triggerBulk')),请求体 BulkTriggerEventDto 仅包含一个 events 数组,数组内的每个元素都是完整的 TriggerEventRequestDto(见 trigger-event-request.dto.ts)。

超过 100 个事件时如何分片

对大批量事件按 100 一组分片,循环发送:

function chunk<T>(array: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size));
  }
  return chunks;
}

const allEvents = users.map((user) => ({
  workflowId: "weekly-digest",
  to: user.id,
  payload: { userName: user.name },
}));

const batches = chunk(allEvents, 100);

for (const batch of batches) {
  await novu.triggerBulk({ events: batch });
}

cURL

curl -X POST https://api.novu.co/v1/events/trigger/bulk \
  -H "Authorization: ApiKey $NOVU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "name": "welcome-email",
        "to": "subscriber-1",
        "payload": { "userName": "Alice" }
      },
      {
        "name": "welcome-email",
        "to": "subscriber-2",
        "payload": { "userName": "Bob" }
      }
    ]
  }'

批量触发要点

  • 单次批量请求最多 100 个事件(SDK 与 API 文档双重声明,见 triggerBulk.ts)。
  • 批量中的每个事件相互独立,可以混用不同的工作流、订阅者与 payload。
  • 成功/失败按单个事件返回,而非整个批次。
  • 若发送量极大(数千级别以上),优先考虑改用主题触发(见下文)。

广播(Broadcast)

向环境内所有订阅者发送通知:

const result = await novu.triggerBroadcast({
  // 这里的 name 字段即 workflowId
  name: "system-announcement",
  payload: {
    message: "Scheduled maintenance at 2am UTC",
  },
});

注意广播 API 的 SDK 签名中字段名为 name(对应 REST 的 POST /v1/events/trigger/broadcast),它扮演的就是 workflowId 的角色。该端点适合发送公告类消息,源码注释还指出未来可能支持基于过滤条件向订阅者子集广播(见 events.controller.ts 与 triggerBroadcast.ts)。广播端点与批量端点都标注了 @ThrottlerCost(ApiRateLimitCostEnum.BULK),即二者共用较高的限流成本策略。

基于主题的触发(Topic-Based Trigger)

主题(Topic)用于向一组订阅者定向发送。流程分三步:创建主题 → 添加订阅者 → 触发到主题。

创建主题并添加订阅者

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

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

// 创建主题
await novu.topics.create({
  key: "project-alpha-watchers",
  name: "Project Alpha Watchers",
});

// 向主题添加订阅者
await novu.topics.subscriptions.create(
  { subscriptions: ["user-1", "user-2", "user-3"] },
  "project-alpha-watchers"
);

触发到单个主题

主题内的所有订阅者都会收到通知:

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

同时触发到多个主题

const result = await novu.trigger({
  workflowId: "company-announcement",
  to: [
    { type: "Topic", topicKey: "engineering-team" },
    { type: "Topic", topicKey: "product-team" },
  ],
  payload: {
    announcement: "Company all-hands at 3pm",
  },
});

cURL

curl -X POST https://api.novu.co/v1/events/trigger \
  -H "Authorization: ApiKey $NOVU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-update",
    "to": {
      "type": "Topic",
      "topicKey": "project-alpha-watchers"
    },
    "payload": {
      "projectName": "Alpha",
      "update": "New release v2.0 deployed"
    }
  }'

主题触发的源码细节

主题目标在 DTO 中由 TopicPayloadDto 定义:topicKey 必填,type 为 TriggerRecipientsTypeEnum。源码还暴露了一个官方文档未强调的可选字段 exclude——用于在主题触发时排除部分订阅者(最大 100 个 ID,字符串数组)。

主题触发要点

  • 触发前必须先创建主题,否则目标不存在。
  • 一个订阅者可同时属于多个主题。
  • 主题触发会向所有成员逐一扇出通知。
  • 同一触发中跨多个主题的重复订阅者会被自动去重(相关行为可参考 e2e 测试 trigger-event-topic.e2e.ts)。

取消触发(Cancel)

对延迟(Delay)或聚合(Digest)类通知,可以使用 transactionId 取消尚未完成的工作流运行:

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

REST 对应的端点是 DELETE /v1/events/trigger/:transactionId(见 events.controller.ts,@SdkMethodName('cancel')),SDK 侧实现见 cancel.ts(DELETE /v1/events/trigger/{transactionId})。接口描述明确指出:使用触发事件时生成的 transactionId,可以取消任何进行中或挂起的工作流,这对取消活跃的 digest、delay 等场景非常有用。

注意:取消功能只对延迟/聚合类通知生效,且没有 transactionId 就无法取消——要么自己传入自定义 ID,要么妥善保存 Novu 生成的 transactionId 以备后续取消。

触发参数速查表

参数 是否必填 说明
workflowId 是 工作流标识符(非显示名称),REST 层字段名为 name
to 是 订阅者 ID(字符串)、订阅者对象或主题目标;数组形式最多 100 个收件人
payload 否 传入工作流的数据,按 payloadSchema 校验;可用于模板渲染与路由规则
overrides 否 按渠道 Provider 的特定覆盖配置(如 providers、layoutId 等)
transactionId 否 唯一 ID,用于幂等去重与后续取消
actor 否 代表“谁触发了动作”的订阅者 ID 或对象
context 否 多租户/组织上下文的键值对,单次触发最多 5 个
tenant 否 租户上下文(字符串或对象),已存在租户会被更新

最佳实践:幂等、错误处理与重试

幂等性:优先使用确定性 transactionId

transactionId 对每个触发事件唯一。若不提供,Novu 会自行生成。它既保证工作流运行的幂等性,也用于后续取消挂起的工作流。相比随机 UUID,基于事件上下文的确定性 ID 更能天然阻止同一事件的重复触发:

import { randomUUID } from "crypto";

const result = await novu.trigger({
  workflowId: "order-confirmation",
  to: "customer-123",
  payload: { orderId: "order-001" },
  transactionId: `order-confirmation-order-001`, // 确定性 ID 防止重复
});

错误处理

针对常见的 HTTP 状态码做区分处理:

try {
  const result = await novu.trigger({
    workflowId: "welcome-email",
    to: "subscriber-123",
    payload: { userName: "Jane" },
  });
  console.log("Triggered successfully:", result);
} catch (error) {
  if (error.statusCode === 422) {
    console.error("Validation error — check payload schema:", error.message);
  } else if (error.statusCode === 401) {
    console.error("Authentication failed — check NOVU_SECRET_KEY");
  } else if (error.statusCode === 404) {
    console.error("Workflow not found — check workflowId");
  } else {
    console.error("Unexpected error:", error);
  }
}

重试策略:指数退避

对瞬时故障(5xx、网络超时等)使用指数退避重试:

async function triggerWithRetry(
  novu: Novu,
  params: TriggerParams,
  maxRetries = 3
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await novu.trigger(params);
    } catch (error) {
      const isRetryable = error.statusCode >= 500 || error.code === "ECONNRESET";
      if (!isRetryable || attempt === maxRetries) throw error;

      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

不可重试的错误(遇到应直接失败,不要重试):

  • 401 — API Key 无效
  • 404 — 工作流不存在
  • 422 — payload 校验失败

值得一提的是,SDK 本身已内置了默认的重试配置:指数退避策略(初始间隔 1000ms、最大间隔 30000ms、指数 1.5、最大耗时 3600000ms),并对 408、409、429 与所有 5XX 状态码自动重试,同时支持通过请求头 idempotency-key 传递幂等键(见 triggerBulk.ts 与 triggerBroadcast.ts)。

Payload 设计

  • 保持 payload 精简——只传 ID 和引用,不要传完整对象。
  • 使用工作流的 payloadSchema 强制校验结构(源码中 payload 不匹配 schema 时返回 400 PayloadValidationExceptionDto,见 events.controller.ts)。
  • 避免在 payload 中携带敏感数据(payload 可能被记录或存储)。
// 推荐:只放引用 ID
{ orderId: "order-001", userId: "user-123" }

// 避免:完整对象携带敏感数据
{ order: { id: "order-001", creditCard: "4111..." } }

主题 vs 批量 vs 广播:如何选择

使用场景 方案
向同一组人群发送相同通知 主题触发
每个订阅者的 payload 各不相同 批量触发
向环境内全部订阅者发送 广播
超过 100 条独立事件 分片批量触发

常见陷阱汇总

  1. workflowId 是标识符而非显示名称——要使用定义工作流时设置的 identifier,而不是人类可读名称;未提供时 Novu 会自动生成 workflowId。
  2. 订阅者自动 upsert——向不存在的 subscriberId 或订阅者对象字符串触发时,Novu 会以该 ID 自动创建订阅者。
  3. 批量触发上限 100 事件——更大批次需要按 100 一组分片。
  4. 取消必须依赖 transactionId——没有它无法取消触发;要么传自定义 ID,要么保存 Novu 生成的 transactionId 以便后续取消工作流运行。
  5. payload 会按工作流的 payloadSchema 校验——若工作流定义了 schema,payload 不匹配时触发会失败(400 校验异常)。

延伸阅读与源码佐证

登录后查看全文
novu