Dify-触发器
本文基于 Dify 官方文档整理,聚焦”如何让一个工作流自动跑起来”这件事。为了方便理解,全文会用一个贯穿始终的例子:每天早上 9 点,自动抓取行业新闻、用 LLM 生成一份早报摘要,推送到企业微信群。
为什么需要触发器?
当你在 Dify 画布上搭建好一个工作流后,它就像一台精密的机器,各个节点是齿轮,连线是传动带。但这台机器需要一个”启动按钮”——触发器就是那个按钮。
没有触发器,工作流只能静静地躺在画布上,等着你来手动点击”运行”。有了触发器,它就能根据你的设定自动启动,真正实现自动化。
回到我们的早报场景:你总不能每天早上 9 点准时坐在电脑前,打开 Dify 点击运行吧?这时候就需要一个触发器,到点自动帮你按下那个按钮。
触发器是什么?
触发器是工作流画布上的”开始节点”,它定义了工作流何时、以何种方式被启动。
如果你用过 Flask 框架,触发器就像是 @app.route() 装饰器——它监听某个条件,条件满足时就执行后面的逻辑。区别在于 Flask 监听的是 HTTP 请求,而 Dify 触发器监听的是时间或外部事件。
Dify 官方文档里没有独立的”hooks”模块,但触发器承担着类似的角色——当某个条件满足时,自动触发一段逻辑。
四种触发方式
Dify 提供四种主要的触发方式,可以用生活中的场景来理解:
- 定时触发器(Schedule Trigger):像墙上的闹钟,到点就响。你设置好时间,它就按时启动工作流,不需要外部干预。
- Webhook 触发器(Webhook Trigger):像家门口的门铃,有人按才响。外部系统发送请求到指定 URL,工作流才会启动。
- 插件触发器(Plugin Trigger):像装了智能门禁系统,外部系统通过插件订阅事件来敲门。比如安装了 GitHub 插件后,仓库有新的 Pull Request 时会自动触发工作流,例如GitHub Actions 等事件。
- 外部定时 + API:像你自己定闹钟,到点后亲自去按别人的门铃。你用外部调度系统(Linux cron、GitHub Actions 等)到点后调用 Dify 的 API,触发工作流。
需要注意的是,触发器只在工作流应用(Workflow App)里可用,聊天流和对话型应用用不了。每个工作流最多只能有一个定时触发器,但可以有多个 Webhook 触发器和插件触发器。
方案一:Schedule Trigger 定时触发器
这是最直接的方案:在工作流里拖一个定时触发器,配置好时间,工作流就会自动跑。
配置步骤
- 打开工作流应用(必须是 Workflow 工作流 类型)。
- 在画布上右键,选择 Add Node -> Start -> Schedule Trigger。
- 在右侧面板选择配置方式:Visual Picker(可视化选择)或 Cron Expression(Cron 表达式)。
- 配置完成后,面板下方会显示接下来 5 次的执行时间,方便确认。
对于”每天早上 9 点”这种简单需求,用 Visual Picker 就够了:频率选 Daily,时间设 09:00。
定时触发器不产生任何输出变量,它只负责启动。但每次触发时,系统变量 sys.timestamp 会被更新为本次执行的开始时间,你可以在下游节点里引用它,比如用 LLM 节点把时间格式化成”2026 年 6 月 17 日 早报”。
Cron 表达式详解
如果需求比较复杂,比如”工作日 9 点到 17 点每 15 分钟一次”,就需要用 Cron 表达式了。
Cron 表达式是 5 段,从左到右依次是:
1 | 分 时 日 月 周 |
用早报场景举例:
0 9 * * *—— 每天 9 点 0 分跑(最常用,对应”每日早报”)0 9 * * MON-FRI—— 周一到周五 9 点跑(工作日早报)*/15 9-17 * * MON-FRI—— 工作日 9 点到 17 点,每 15 分钟一次(适合实时舆情监控)0 0 1 * *—— 每月 1 号 0 点跑(月度汇总)0 17 L * *—— 每月最后一天 17 点跑(L表示 last)
几个特殊字符的含义:
*表示”每”。写在”时”的位置就是”每小时”。,表示”和”。1,3,5写在”周”的位置就是”周一、周三、周五”。-表示”到”。9-17写在”时”的位置就是”9 点到 17 点”。/表示”每隔”。*/15写在”分”的位置就是”每 15 分钟”。L表示”最后一个”。写在”日”的位置就是”本月最后一天”。
还有几个预定义的快捷写法:
@daily等价于0 0 * * *(每天 0 点)@hourly等价于0 * * * *(每小时整点)@weekly等价于0 0 * * 0(每周日 0 点)@monthly等价于0 0 1 * *(每月 1 号 0 点)@yearly等价于0 0 1 1 *(每年 1 月 1 号 0 点)
Dify 的 Cron 表达式输入框旁边有个”用 LLM 生成”的按钮,你直接用自然语言说”每个工作日早上 9 点”,它会帮你生成表达式。
测试方法
定时触发器有两种测试方式:
- Run this step(单步运行):立刻执行一次,忽略你配的定时。适合调试工作流本身。
- Test Run(整体试跑):会真的等到下一个定时点才跑。适合验证时间配置是否正确。
调试阶段用第一种,确认时间配置用第二种。
方案二:外部定时 + Workflow Run API
如果你是自部署 Dify,或者想把定时逻辑放在自己的服务器上,可以用外部定时器到点后调用 Dify 的 API 来触发工作流。
这种方式和方案一的本质区别是:方案一的闹钟装在 Dify 内部,方案二的闹钟装在外部,到点后外部”敲门”叫醒 Dify。
方案二的好处是定时逻辑完全在你手里,可以用任意语言、任意调度系统,甚至接入更复杂的企业级调度(如 Airflow)。坏处是你得自己维护一个外部服务。
Workflow Run API 调用详解
核心接口是 POST /workflows/run,用于执行一个已发布的工作流。调用前必须先在 Dify 里把工作流”发布”,否则会报错。
请求示例
1 | curl --request POST \ |
关键参数说明:
inputs:工作流的输入变量,键值对形式。变量名要和工作流开始节点里定义的一致。如果没有输入变量,传{}。response_mode:响应模式,有 blocking 和 streaming 两种,下面会详细说明。user:用户标识符,必填。用于区分是谁触发的这次执行,比如定时任务就用cron-job-001。
响应示例(blocking 模式)
1 | { |
workflow_run_id:本次执行的唯一 ID,后续查日志、查详情都用它。data.status:执行状态,succeeded/failed/stopped。data.outputs:工作流最终输出的变量,对应结束节点里定义的输出。
blocking 和 streaming 的区别
这两个模式是 Dify API 里最容易混淆的概念,可以用”取快递”来理解:
- blocking(阻塞模式):你下单后站在门口等,快递员把东西送到手你才走。API 调用会一直等,直到工作流跑完才返回最终结果。
- streaming(流式模式):你下单后,快递员每装好一箱就给你发个短信,你边收短信边看进度。API 会持续返回一个个事件。
对于定时任务,绝大多数情况用 blocking 就够了——你只关心最终结果,不需要看中间过程。Dify Cloud 上 blocking 模式有 100 秒的超时限制,如果工作流跑得超过 100 秒,就得改用 streaming,或者把工作流拆短。
Python 脚本示例
下面是一个 Linux cron + Python 的完整例子,每天早上 9 点调用 Dify 工作流生成早报。
1 | import requests |
Linux cron 配置
1 | crontab -e |
注意时区问题:Linux 服务器默认用系统时区,Dify Cloud 默认是 UTC。如果你的服务器是北京时间(UTC+8),而 Dify 显示的执行时间是 UTC,记得换算。
更省事的方案:dify-schedule
社区有个开源项目 dify-schedule,它直接用 GitHub Actions 当定时器,到点调用 Dify 工作流,还内置了企业微信、钉钉、飞书、邮件等多种通知渠道。
用法很简单:
- Fork 这个仓库。
- 在仓库的 Settings -> Secrets 里配置:
DIFY_TOKENS:你的工作流 API Key(多个用;分隔)。DIFY_BASE_URL:Dify API 地址,默认https://api.dify.ai/v1。DIFY_INPUTS:工作流输入变量,JSON 格式。
- 到 Actions 页面启用 workflow。
- (可选)配置通知渠道的 Secret,比如
WEIXIN_WEBHOOK推送到企业微信。
这个方案零运维、免费(GitHub Actions 公开仓库免费),适合个人或小团队。缺点是执行时间受 GitHub Actions 调度影响,可能延迟几十秒到几分钟,不适合对时间精度要求高的场景。
方案三:Webhook Trigger Webhook 触发器
前面两种方案都是”到点就跑”,但有些场景是”事情发生了才跑”:
- 用户在企业微信群里 @机器人提问,机器人立刻回答
- GitHub 仓库收到新的 Issue,自动分类并指派
- 电商系统收到新订单,自动生成发货单
这些场景没有固定时间,事件来了才触发。Webhook 触发器就是干这个的。
配置与测试完整示例
下面以”用户在企业微信 @机器人时,触发工作流回答问题”为场景,用一个完整的例子演示 Webhook 触发器的配置和测试流程。
假设你自部署了 Dify,nginx 对外开放端口 8083(这也是你访问 Dify Web 界面的地址)。
第一步:配置环境变量
在 Dify 的 .env 文件或 docker-compose.yaml 中设置:
1 | TRIGGER_URL=http://localhost:8083 |
这样 Dify 生成的 Webhook URL 前缀就会变成 http://localhost:8083,外部系统可以通过 nginx 访问到 Dify API。默认前缀是 http://localhost,必须修改为外部系统实际能访问到的地址。
第二步:添加 Webhook Trigger 节点
在工作流画布右键,选择 Add Node -> Start -> Webhook Trigger。添加后,配置面板会显示两个不同的 URL:
- Test Webhook URL:用于测试调试。当你点击 “Run this step” 进入监听状态时,必须使用这个 URL。
- Production Webhook URL:用于生产运行。工作流发布后,外部系统正式调用时使用这个 URL。
假设 Webhook ID 为 yfEPdcPa0wmmUBH9T7DKQKRF,两个 URL 示例:
- Test URL:
http://localhost:8083/triggers/webhook/yfEPdcPa0wmmUBH9T7DKQKRF - Production URL:
http://localhost:8083/triggers/webhook/production/另一个ID
⚠️ 关键提醒:两者的 Webhook ID 完全不同,请求必须发送到正确的 URL 才能生效。一个常见的错误是在测试模式下发送请求到 Production URL,结果请求返回 { "status": "success" },但 Dify 界面上 Last Run 标签页没有任何记录。请务必从配置面板直接复制对应的 URL。
第三步:配置请求参数
在 Webhook Trigger 节点的右侧配置面板,设置以下内容:
HTTP 方法:选择 POST(最常用)。必须和外部系统发请求时用的方法一致,否则请求会被拒绝。
Content-Type:选择 application/json。同样必须和外部系统一致。
参数提取:外部请求里带的数据,需要告诉 Dify “提取哪几个字段”。每个提取的参数会变成输出变量,下游节点可以用 {{变量名}} 引用。
参数可以从三个地方提取:
- Query Parameters:URL 里
?后面的键值对,如?userID=u-456 - Header Parameters:请求头字段,注意连字符
-会自动转成下划线_ - Request Body Parameters:请求体里的核心数据,最常用
对于企业微信场景,配置以下请求体参数:
msg_type:String,必填content:String,必填user_id:String,必填
勾选”必填”后,如果请求里没带这个参数,工作流不会触发。
响应配置(可选):Dify 默认返回 200 OK。如果外部系统要求特定格式(如企业微信要求返回特定 JSON),可自定义状态码和响应体。
第四步:测试运行
未发布的触发器,必须先进入”监听状态”才能接收请求。
- 在 Webhook Trigger 节点点击 **”Run this step”**,节点进入监听状态。
- 打开 Postman,配置请求:
- Method:
POST - URL:
http://localhost:8083/triggers/webhook/yfEPdcPa0wmmUBH9T7DKQKRF(必须使用 Test URL) - Headers:
Content-Type: application/json - Body(raw JSON):
1
2
3
4
5{
"msg_type": "text",
"content": "今天有什么AI新闻?",
"user_id": "user-001"
}
- Method:
- 点击 Send 发送请求。
- 查看结果:
- Postman 收到响应:
{ "status": "success" } - Dify 界面切换到 Last Run 标签页,查看收到的请求记录
- 确认参数提取是否正确,下游节点是否开始执行
- Postman 收到响应:
如果 Last Run 没有记录,检查是否使用了正确的 Test URL。
第五步:发布生产
测试通过后,点击右上角 Publish 发布工作流。发布后,外部系统使用 Production URL 调用即可触发完整的工作流执行。
curl 调用示例(生产环境):
1 | curl --request POST \ |
请求发出后,Dify 返回 200 OK,工作流开始执行。下游节点用 {{content}} 引用用户问题,LLM 生成回答后,通过 HTTP Request 节点推回企业微信。
方案四:Plugin Trigger 插件触发器
前面的 Webhook 触发器需要你手动配置外部系统的回调地址,而插件触发器更进一步——它通过官方或社区开发的触发器插件,帮你自动完成外部系统的事件订阅。
插件触发器就像是给你的工作流装了一套智能门禁系统。安装好插件后,门禁系统会自动连接到外部系统(比如 GitHub、飞书、企业微信),当外部系统发生特定事件时,门禁系统会自动开门,让工作流开始执行。
插件触发器和 Webhook 触发器的区别
用 GitHub 场景举例:
- Webhook 触发器:你需要在 GitHub 仓库的 Settings -> Webhooks 里手动添加 Dify 的 Webhook URL,选择要监听的事件,然后在 Dify 里配置要提取的参数。
- 插件触发器:你安装 GitHub 触发器插件后,在 Dify 里授权,插件会自动帮你在 GitHub 上创建 Webhook,你只需要选择要订阅的事件(如 Pull Request、Push、Issue),然后把对应的插件触发器拖到工作流画布上即可。
插件触发器是 Webhook 触发器的”封装版”,省去了你手动配置外部系统 Webhook 的步骤,同时还提供了标准化的事件参数提取。
配置步骤
第一步:添加节点
在工作流画布右键,选择 Add Node -> Start,然后从可用的插件触发器中选择,或者在 Dify Marketplace 搜索更多。
如果没有合适的触发器插件,你可以:
- 向社区请求开发。
- 自己开发一个触发器插件。
- 改用 Webhook 触发器。
第二步:选择或创建订阅
每个插件触发器都需要关联一个订阅。订阅本质上是一个 Webhook,用于监听外部系统的事件。
一个工作流可以有多个插件触发器。如果这些触发器分支共享相同的下游节点,可以添加 Variable Aggregator 节点把它们汇合,避免重复画节点。
创建订阅有三种方式:
- OAuth 自动创建:选择要订阅的事件,Dify 通过 OAuth 授权自动在外部系统创建 Webhook。很多热门插件都预置了默认的 OAuth 客户端,一键授权即可。
- API Key 自动创建:输入 API Key 等认证信息,Dify 自动在外部系统创建 Webhook。
- 手动创建:使用 Dify 提供的回调 URL,自己在外部系统创建 Webhook。
第三步:配置其他设置
根据插件的要求,配置必要的参数。插件触发器的输出变量由插件定义,不能修改。
示例:GitHub Pull Request 触发器
假设你想在 GitHub 仓库收到新的 Pull Request 时,自动触发工作流进行代码审查。
配置步骤:
- 在工作流画布添加 GitHub Pull Request 插件触发器。
- 选择 Create with OAuth,使用默认 OAuth 客户端。
- 在弹出的 GitHub 授权页面上,授予 Dify 访问权限。
- 选择订阅的仓库和事件(如 Pull Request -> opened)。
- 点击创建,插件会自动在 GitHub 上创建 Webhook。
配置完成后,当有人打开 Pull Request 时,工作流会自动触发,插件触发器会输出 Pull Request 的详细信息(标题、作者、分支、文件变更等),下游节点可以直接使用这些变量。
测试方法
未发布的插件触发器,必须先点 Run this step 或整体试跑,让它进入”监听状态”,才能捕获订阅的事件。否则即使外部系统发生了事件,工作流也不会触发。
四种方案怎么选?
回到我们的早报场景,给一个明确的选型建议:
首选方案一(Schedule Trigger),理由:
- 需求就是”到点跑”,没有外部事件触发。
- 不想维护外部服务器。
- 配置最简单,5 分钟搞定。
什么时候用方案二(外部定时 + API):
- Dify 是自部署的,且定时触发器功能受限或不可用。
- 定时逻辑很复杂,比如”每月最后一个工作日 9 点”这种 Cron 不好表达的。
- 需要和企业级调度系统(Airflow、DolphinScheduler)集成。
- 需要在调用前后做额外处理(比如先从数据库取参数,调用后写日志到 ELK)。
什么时候用方案三(Webhook Trigger):
- 触发时机不是”到点”,而是”事件发生”。
- 外部系统支持 Webhook,但没有现成的 Dify 触发器插件。
- 需要完全自定义请求参数的提取逻辑。
- 比如早报场景升级:不再固定 9 点推,而是”每当有重要新闻入库,立刻生成快讯推送”——这时候就用 Webhook,让新闻系统入库时调你的 Webhook URL。
什么时候用方案四(Plugin Trigger):
- Dify Marketplace 上有对应外部系统的触发器插件。
- 想省去手动配置外部系统 Webhook 的步骤。
- 需要标准化的事件参数提取,不想自己解析请求体。
- 比如”GitHub 有新的 Pull Request 时自动触发代码审查”、”飞书收到新消息时自动回复”这类场景,用插件触发器比 Webhook 触发器更便捷。
四种方案能混着用吗?
能。一个工作流可以有多个触发器并行存在(但定时触发器最多一个)。比如同一个早报工作流,可以同时挂:
- 一个 Schedule Trigger:每天 9 点定时推。
- 一个 Webhook Trigger:管理员随时手动触发”立即推送”。
- 一个 Plugin Trigger:通过飞书插件,管理员在飞书里发指令触发推送。
多个触发器共享同一套下游节点。如果不同触发器分支需要汇合,用 Variable Aggregator(变量聚合器)节点把各分支的变量收拢,避免重复画节点。
注意:Dify Cloud 上触发器执行次数有配额限制,不同套餐不一样。工作区所有者和管理员可以在 Settings -> Billing 里查看剩余配额。Sandbox 套餐每个工作流最多 2 个触发器。
常见问题与排查
定时触发器配好了但没执行
按这个顺序排查:
- 触发器是否已发布:在 Quick Settings 侧边栏能看到并启用,才算发布生效。没发布的触发器不会执行。
- 时区是否对得上:Dify Cloud 默认 UTC,你配的”9 点”可能是 UTC 9 点(北京时间 17 点)。自部署看服务器时区。
- 看 Logs:工作流应用的 Logs 里会显示每次执行的触发来源,确认是不是定时触发器触发的。
- 配额是否用完:Dify Cloud 上触发器执行有配额,用完了就不会触发。
Webhook 触发器收不到请求
- 是否处于监听状态:未发布的触发器,必须先 Run this step 才能收请求。
- HTTP 方法是否匹配:你配的是 POST,外部发的 GET,会被拒绝。
- Content-Type 是否匹配:你配的是 application/json,外部发的 form-data,会被拒绝。
- URL 是否可达:自部署环境下,
TRIGGER_URL必须是外部系统能访问到的公网地址。本地开发可以用 ngrok 做内网穿透。 - 必填参数是否齐全:少一个必填参数,工作流不会触发。
API 调用返回 404 或 401
- 401 Unauthorized:API Key 错了,或者没加
Bearer前缀。注意是Authorization: Bearer app-xxxx,不是直接app-xxxx。 - 404 Not Found:工作流没发布,或者 URL 写错了。确认工作流已发布,且 URL 是
https://api.dify.ai/v1/workflows/run(自部署换成你的域名)。 - 400 Bad Request:请求体格式不对,或者
inputs里的变量名和工作流定义的对不上。
插件触发器收不到事件
- 是否已创建订阅:插件触发器必须关联一个有效的订阅,订阅本质上是一个 Webhook。没有订阅或订阅已过期,就收不到事件。
- 订阅是否包含该事件:创建订阅时需要选择要监听的事件类型。如果当前事件不在订阅列表中,工作流不会触发。建议创建订阅时勾选所有可用事件。
- OAuth 授权是否有效:如果使用 OAuth 方式创建订阅,授权可能已过期或被撤销。可以在插件详情页重新授权。
- 是否处于监听状态:未发布的触发器,必须先点 Run this step 才能捕获事件。
- 检查请求日志:在订阅的手动设置页面,可以查看请求日志,确认外部系统是否发送了请求,以及 Dify 是否正确响应。
总结
最后用我们的早报场景把四种方案串一遍:
1 | 场景:每天 9 点生成行业早报推送到企业微信 |
记住一个核心区别:
- 定时触发器 = 闹钟:到点响。
- Webhook 触发器 = 门铃:有人按才响。
- 插件触发器 = 智能门禁:外部系统通过插件自动触发。
- 外部定时 + API = 你自己定闹钟去按别人的门铃。
选哪种,看你的”响铃条件”是时间还是事件,以及外部系统是否有现成的触发器插件。
参考文档
- 触发器总览:https://docs.dify.ai/en/use-dify/nodes/trigger/overview
- 定时触发器:https://docs.dify.ai/en/use-dify/nodes/trigger/schedule-trigger
- Webhook 触发器:https://docs.dify.ai/en/use-dify/nodes/trigger/webhook-trigger
- 插件触发器:https://docs.dify.ai/en/cloud/use-dify/nodes/trigger/plugin-trigger
- 执行工作流 API:https://docs.dify.ai/api-reference/workflows/run-workflow
- API 集成指南:https://docs.dify.ai/en/use-dify/publish/developing-with-apis
- 社区定时方案 dify-schedule:https://github.com/leochen-g/dify-schedule