#2. 触发器

触发器是一类特殊的开始节点。普通的开始节点要等访客交互或 API 调用才会启动工作流，触发器则让工作流自动跑起来——既可以按设定的时间表定时运行，也可以在外部系统（如 GitHub、Gmail，或自建的内部系统）发生某个事件时被动触发。

这一机制特别适合两类场景：把重复性的例行任务交给系统自动完成，以及把工作流与第三方应用打通，实现数据的自动同步与处理。

一个工作流可以同时挂多个触发器并行工作。同一画布上也能搭建多条相互独立的工作流，各自以自己的触发器为起点。

#触发器类型

触发器分为三种，分别对应「按时间」和「按事件」两类启动方式。

• 定时触发器（Schedule Trigger） 按指定的时间点或时间间隔运行工作流。例如每天早上 9 点自动生成销售日报并邮件发给团队。每个工作流最多只能有一个定时触发器。

• 插件触发器（Plugin Trigger） 借助触发器插件订阅外部系统的事件，当事件发生时自动运行工作流。例如通过 Slack 触发器插件订阅「频道新消息」事件，每当指定频道来了新消息，就自动分析并归档。

• Webhook 触发器（Webhook Trigger） 通过自定义 Webhook，在外部系统发生事件时运行工作流。例如电商平台下了新订单后，向 Webhook 发来一个带订单详情的 HTTP 请求，工作流随即自动处理这笔订单。

插件触发器和 Webhook 触发器都属于事件驱动，两者的取舍很简单：目标外部系统已有现成的触发器插件时，优先用插件触发器，订阅对应事件即可；若没有现成插件，或要捕获插件不支持的事件，则用 Webhook 触发器，自行在外部系统里配置 Webhook。

#启用与停用触发器

在界面左上角「快捷设置」侧边菜单里可以启用或停用已发布的触发器，停用后的触发器不再发起工作流运行。注意，只有已发布的触发器才会出现在快捷设置里；如果某个已添加的触发器没列出来，先确认它是否已发布。

#测试多个触发器

工作流挂了多个触发器时，可点击「测试运行 > 运行所有触发器」一次性测试。最先被激活的那个触发器会发起工作流，其余的随后被忽略。点击「运行所有触发器」后，定时触发器会等到下一个计划运行时间执行，插件触发器开始监听所订阅的事件，Webhook 触发器开始监听外部 HTTP 请求。

#定时触发器

定时触发器让工作流在指定的时间点或时间间隔运行，适合生成日报、定时发通知这类周期性任务。每个工作流最多只能有一个定时触发器。

添加方式

点击「添加节点 > 开始 > 定时触发器」即可添加。

配置方式

时间表可以用默认的可视化选择器配置，也可以写 cron 表达式。配置好后，界面会列出接下来 5 次的运行时间，便于核对。

定时触发器本身不产生输出变量，但每次发起工作流时，都会更新系统变量 sys.timestamp（即本次运行的开始时间）。

可视化选择器

适合按小时、按天、按周、按月这类简单规律。选周和月时，还能勾选多个具体的星期或日期。

cron 表达式

适合更复杂、更精确的时间规律，比如「工作日 9 点到 17 点之间每隔 15 分钟」。写不出来时，可借助 LLM 生成 cron 表达式。

一条 cron 表达式由空格分隔的五个字段组成，每个字段代表一个时间单位，字段之间务必只留一个空格：

* * * * *
| | | | |
| | | | └── 星期几（0-7 或 SUN-SAT，0 和 7 都表示周日）
| | | └──── 月份（1-12 或 JAN-DEC）
| | └────── 日（1-31）
| └──────── 小时（0-23）
└────────── 分钟（0-59）

需要留意的是，当「日」和「星期几」两个字段都填了具体值时，触发条件是「满足其一即可」，而非同时满足。例如 1 2 3 4 4 会在 4 月 3 日、以及 4 月的每个周四都触发，并不是只在「正好是 3 号的周四」才触发。

常用特殊字符：* 表示「每」（小时字段里的 * 即「每小时」）；, 分隔多个值（星期字段里的 1,3,5 即周一、周三、周五）；- 表示区间（小时字段里的 9-17 即 9 点到 17 点）；/ 表示步进（分钟字段里的 */15 即每 15 分钟）；L 表示「最后」（日字段里即当月最后一天，星期字段里的 5L 即当月最后一个周五）；? 表示「任意／不指定」，当一个字段已填具体值时，可用 ? 让另一个相关字段不参与判断。

也可直接使用预定义表达式：@yearly（每年 1 月 1 日零点）、@monthly（每月 1 日零点）、@weekly（每周日零点）、@daily（每天零点）、@hourly（每小时整点）。

几个示例：工作日 9 点写作 0 9 * * MON-FRI；每周三 14:30 写作 30 14 * * WED；每月 1 日零点写作 0 0 1 * *；每月最后一天 17 点写作 0 17 L * *。

提示：不同系统对 cron 的高级语法支持可能不同。如果需要“每月最后一天”“复杂节假日规则”等场景，建议优先使用 Dify 界面的可视化选择器，或先在测试环境验证表达式是否按预期运行。

测试方式

点击「运行此步骤」，定时触发器会立即运行一次，忽略所配置的时间表；点击「测试运行」，则会按时间表等到下一个计划运行时间才执行。

#插件触发器

插件触发器在外部系统发生某个事件时自动启动工作流。整个过程只需两步：通过触发器插件订阅这些事件，再把对应的插件触发器加进工作流。

举例来说，装好 GitHub 触发器插件后，它会列出一批可订阅的 GitHub 事件，比如 Pull Request、Push、Issue。订阅 Pull Request 事件、并把 Pull Request 插件触发器加进工作流后，只要指定仓库里有人提了 PR，工作流就会自动运行。

添加与配置

点击「添加节点 > 开始」，选用插件触发器并关联一个订阅，再按提示完成其余设置即可。

插件触发器的输出变量由其插件本身定义，不可修改。一个工作流可挂多个插件触发器；若这些触发分支共用相同的下游节点，可加一个变量聚合器（Variable Aggregator）把它们汇合，避免在每条分支上重复搭建相同节点。

新建订阅

每个触发器插件在一个工作区内最多可建 10 个订阅。

每个订阅的底层都是一个 Webhook——新建订阅，实质上就是配置一个监听外部系统事件的 Webhook。（Webhook 指一个系统在某事件发生时，把事件详情打包成 HTTP 请求，自动发送到另一个系统指定的 URL，从而实现数据的实时推送。）

Dify 提供两种建订阅（即建 Webhook）的方式，具体哪种可用取决于插件的设计：

• 自动创建：选好要订阅的事件，由 Dify 自动在外部系统里把对应的 Webhook 建好。这需要事先通过 OAuth 或 API 密钥授权，Dify 才能代为操作。

• 手动创建：用 Dify 提供的回调 URL，自行在外部系统里建 Webhook，无需授权。

建议新建订阅时把所有可选事件都勾上。插件触发器只有在所订阅的事件包含它对应的事件时才工作，全选可以保证日后往工作流里加的任何同类插件触发器都能复用这个订阅，省去反复改动或新建的麻烦。

自动创建中的 OAuth 方式：Dify Cloud 上不少常用插件已预置默认 OAuth 客户端，一键即可授权；自托管部署只能用自定义 OAuth 客户端，需要自行在外部系统里创建 OAuth 应用，再把客户端 ID 和密钥填回 Dify。API 密钥方式则是填入认证信息、验证通过后，设定订阅名、勾选事件即可创建。手动创建则是用 Dify 给的回调 URL 自行到外部系统建 Webhook，建完可选地发一个事件做测试，在「手动设置」页底部的「请求日志」里核对收到的请求和 Dify 的响应。

授权流程中显示的回调 URL 由 Dify 内部使用，用于代建 Webhook，无需对它做额外操作。自托管部署可通过 TRIGGER_URL 环境变量修改该 URL 的前缀，并确保前缀指向外部系统可访问的公网域名或 IP。

测试方式

测试尚未发布的插件触发器前，必须先选中节点，点击「运行此步骤」或测试运行整个工作流，让触发器进入监听状态，否则即便订阅的事件真的发生，触发器也捕获不到。

#Webhook 触发器

Webhook 指一个系统在某事件发生时，把事件详情打包成 HTTP 请求，自动发送到另一个系统指定的 URL。Webhook 触发器正是基于这一机制，让工作流响应第三方事件而运行。整个流程如下：

1. 往工作流里加一个 Webhook 触发器时，系统会生成一个唯一的 Webhook URL，作为专门监听外部 HTTP 请求的端点。（自托管部署可通过 TRIGGER_URL 环境变量修改该 URL 的前缀，确保它指向外部系统可访问的公网域名或 IP。）
2. 拿这个 URL 到外部系统里建一个 Webhook，订阅想监听的事件；再配置 Webhook 触发器，定义它如何处理收到的请求、从中提取哪些数据。测试时务必使用测试专用的 Webhook URL，把测试数据和生产数据隔开。
3. 订阅的事件发生时，外部系统把带事件数据的 HTTP 请求发到这个 URL；请求被成功接收并处理后，工作流随即触发，指定的数据被提取成变量，供下游节点引用。

若目标外部系统已有现成的触发器插件，建议优先用插件触发器。

添加方式

「添加节点 > 开始 > Webhook 触发器」即可添加。

提示：一个工作流可挂多个 Webhook 触发器；若这些分支共用相同的下游节点，可加变量聚合器把它们汇合，避免重复搭建。

配置方式

Webhook 触发器需要定义如何处理传入的 HTTP 请求，包括四方面：接受的 HTTP 方法、请求的内容类型、要从请求中提取的数据，以及成功触发后回给外部系统的响应。

HTTP 方法

需指定 Webhook URL 接受哪种 HTTP 方法。这里选的方法必须和外部系统实际发请求用的方法一致，否则请求会被拒收。这个信息通常能在外部系统的 Webhook 文档或配置界面里找到。

内容类型（Content-Type）

需指定传入请求的内容类型，请求体才能被正确解析、数据才能被提取出来。这里选的内容类型必须和外部系统实际发送的一致，否则请求会被拒收。

提取查询参数、请求头参数、请求体参数（Query / Header / Request Body Parameters）

可以从传入请求的查询参数、请求头、请求体中提取所需数据，每个提取出的参数都会成为一个可在工作流中使用的输出变量。

一些外部系统会为每次请求提供投递日志，可在其中查看请求所含的全部数据，据此决定提取哪些参数。也可以自己发一个测试请求，再到触发器的「上次运行」里查看收到的请求数据，步骤是：在外部系统用测试 Webhook URL 建好 Webhook、在触发器里设好正确的 HTTP 方法和内容类型、点击「运行此步骤」让触发器开始监听、在外部系统触发所订阅的事件使其发出请求、最后在触发器「上次运行」的「输入」里查看收到的数据。注意，触发器里定义的变量名必须和请求中对应参数的键名一致。

三类参数各有特点：

• 查询参数：外部系统发请求时拼在 Webhook URL 问号 ? 之后的键值对，多个之间用 & 隔开，通常是简单、非敏感的标识或筛选信息。例如从 {webhook url}?userID=u-456&source=email 中可提取 userID（值为 u-456）或 source（值为 email）。
• 请求头参数：放在请求头里的元信息，是处理请求所需的技术性信息，比如认证令牌、请求体的数据格式。例如从 Authorization: Bearer sk-abc... 和 Content-Type: application/json 中可提取认证信息或内容类型。
• 请求体参数：承载核心事件数据的主体，比如客户资料、订单详情、Slack 消息内容等。例如从下面的请求体中可提取 customerName（值为 Alex）、商品列表，或 isPriority 状态（值为 true）：

{
  "customerName": "Alex",
  "items": [
    { "sku": "A42", "quantity": 2 },
    { "sku": "B12", "quantity": 1 }
  ],
  "isPriority": true
}

能从请求体中提取哪些数据类型，取决于内容类型：application/json 支持字符串、数字、布尔、对象及各类数组（不含文件）；application/x-www-form-urlencoded 支持基础类型和基础类型的数组；multipart/form-data 在前者基础上额外支持文件和文件数组；text/plain 只支持字符串、数字、布尔三种基础类型。

每个待提取的参数可设定三项：变量名（请求中该参数的键名，如 userID=u-456 里的 userID；请求头参数名里的连字符 - 会在输出变量中自动转成下划线 _）、数据类型（预期的数据格式，仅查询参数和请求体参数可设，请求头参数一律按字符串处理）、是否必填（缺少任一必填参数的请求都不会触发工作流）。

响应（Response）

工作流被外部请求成功触发后，默认回传一个 200 OK 响应。若外部系统要求特定的成功响应格式，可自定义状态码和响应体来覆盖默认值：状态码支持 [200, 399] 区间内的任意值；响应体支持 JSON 或纯文本，其中非 JSON 内容会自动转成 JSON（例如 OK 会被包成 "message": "OK"）。

以下错误响应由系统定义、不可自定义，具体错误信息见响应体：400 Bad Request、404 Not Found、413 Payload Too Large、500 Internal Server Error。

测试方式

测试未发布的 Webhook 触发器前，必须先选中节点，点击「运行此步骤」或测试运行整个工作流，让触发器进入监听状态，否则传入的请求不会被捕获。