Novu 触发通知(Trigger Notification)完整指南:单次、批量、广播、主题触发与取消
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 时返回 400PayloadValidationExceptionDto,见 events.controller.ts)。 - 避免在 payload 中携带敏感数据(payload 可能被记录或存储)。
// 推荐:只放引用 ID
{ orderId: "order-001", userId: "user-123" }
// 避免:完整对象携带敏感数据
{ order: { id: "order-001", creditCard: "4111..." } }
主题 vs 批量 vs 广播:如何选择
| 使用场景 | 方案 |
|---|---|
| 向同一组人群发送相同通知 | 主题触发 |
| 每个订阅者的 payload 各不相同 | 批量触发 |
| 向环境内全部订阅者发送 | 广播 |
| 超过 100 条独立事件 | 分片批量触发 |
常见陷阱汇总
workflowId是标识符而非显示名称——要使用定义工作流时设置的 identifier,而不是人类可读名称;未提供时 Novu 会自动生成workflowId。- 订阅者自动 upsert——向不存在的
subscriberId或订阅者对象字符串触发时,Novu 会以该 ID 自动创建订阅者。 - 批量触发上限 100 事件——更大批次需要按 100 一组分片。
- 取消必须依赖
transactionId——没有它无法取消触发;要么传自定义 ID,要么保存 Novu 生成的transactionId以便后续取消工作流运行。 - payload 会按工作流的
payloadSchema校验——若工作流定义了 schema,payload 不匹配时触发会失败(400 校验异常)。
延伸阅读与源码佐证
- 完整参考手册:安装与初始化、单次触发示例、批量触发示例、主题触发示例、最佳实践。
- 触发入口与路由:events.controller.ts(
POST /trigger、POST /trigger/bulk、POST /trigger/broadcast、DELETE /trigger/:transactionId)。 - 请求体定义与校验规则:trigger-event-request.dto.ts。
- SDK 方法定义:sdk.ts(
trigger/triggerBulk/triggerBroadcast/cancel)。 - SDK 实现细节:trigger.ts、triggerBulk.ts、triggerBroadcast.ts、cancel.ts。
- e2e 测试佐证:trigger-event.e2e.ts、bulk-trigger.e2e.ts、trigger-event-topic.e2e.ts、cancel-event.e2e.ts。
- 工作流侧的设计(渠道、严重级别、digest、条件、模板等)属于另一个技能主题,可参考 design-workflow 相关文档,本指南聚焦于触发(trigger)侧实践。