Dify中通过外部Webhooks接收系统事件通知的方法

您是否希望让 Dify 能够主动“感知”外部系统的事件？例如，当 GitHub 上有代码提交时自动触发 AI 工作流，或者在 CRM 中新建客户后立即启动后续处理流程。要实现这一目标，核心在于通过 Webhook 将 Dify 配置为一个安全的接收端点，实时捕获并解析外部系统发来的结构化数据。整个过程并不复杂，但需要正确执行几个关键步骤。

首先需要明确一个核心概念：整体流程本质上是创建一个可验证的 HTTP 端点，让 Dify 能够安全地与外部系统进行“握手”。下面将分步详细说明具体操作方法。

创建入站 Webhook 应用

第一步，进入 Dify 控制台，在应用列表点击“+新建应用”，选择“空白应用”，为其命名后单击“创建”。此操作相当于为 Dify 开启了一个专门接收外部信号的“入口”。

应用创建完成后，在左侧导航栏找到“设置”→“API 密钥”，点击“生成新密钥”，并务必复制并妥善保存生成的密钥。需要反复提醒的是：该密钥是后续签名验证的唯一凭证，一旦丢失将无法找回。它就像一把钥匙——丢了便无法开启对应的门。

接下来，返回应用首页，点击右上角的“发布”，在弹出的面板中切换到“Webhook”标签页，打开“启用 Webhook”开关，然后点击“复制 URL”获取唯一的入站地址。这个 URL 的格式类似：https://api.dify.ai/v1/webhooks/abc123。它就是 Dify 对外开放的接口。

配置外部系统发送请求

外部系统向 Dify 发送请求时，必须遵守以下硬性规则。首先，请求方法必须是 POST；其次，请求体必须是 UTF-8 编码的 JSON 对象；最后，该 JSON 必须包含两个字段：event（事件类型标识）和 payload（业务数据）。示例如下：

{ "event": "github.push", "payload": { "repository": "my-app", "branch": "main", "commits": 3 } }

当然，仅发送内容还不够，还需证明该请求是由授权方发起的。所有请求都必须携带一个 X-Dify-Signature 请求头，其值使用 HMAC-SHA256 算法，以之前生成的 API 密钥作为密钥，对原始 JSON 字符串进行哈希计算后再进行 base64 编码。未携带签名或签名验证失败的请求，Dify 会返回 401 状态码，直接拒绝。

如果您习惯使用 curl 进行测试，可参考以下命令模板：

curl -X POST https://api.dify.ai/v1/webhooks/abc123 \
-H "Content-Type: application/json" \
-H "X-Dify-Signature: sha256=xxxxxx" \
-d '{"event":"test","payload":{"id":123}}'

绑定事件与工作流

上述配置仅搭建了通信通道，要让 Dify 真正“响应”事件，还需将事件与工作流进行绑定。

第一步，在 Dify 应用内构建一个工作流，该工作流至少应包含一个“开始节点”和一个“大模型节点”。没有工作流，事件到来后也无法执行任何操作。

第二步，回到“设置”→“Webhook”页面，在“事件类型”下拉框中选择外部系统发送的 event 值——例如 github.push。选中后，点击右侧的“绑定工作流”，从列表中选择刚才创建的工作流，再点击“保存”。这一步相当于给 Dify 下达指令：当接收到“GitHub 推送”事件时，立即启动指定的工作流程。

第三步，当 Dify 收到匹配的 event 请求后，它会自动将整个 JSON 载荷注入到工作流上下文中。这意味着，您可以在工作流的提示词中使用 {{payload.repository}} 或 {{event}} 等语法引用对应字段。如果外部请求中的 event 值未在下拉列表中列出，则该请求不会触发任何流程，相当于被忽略。

需要特别注意：绑定操作是不可逆的。如果之后需要修改事件类型，必须先解绑再重新选择，无法直接覆盖。

验证请求是否成功到达

配置完成后，如何确认 Dify 是否成功接收信号并启动了工作流？以下是几种简单直接的方法。

方法一：在 Dify 应用的日志页面（路径为“监控”→“日志”），筛选关键词“webhook”，查看是否有状态码 200 的记录以及解析出的 payload 内容。存在记录说明信号已接收，反之则说明信号丢失。

方法二：在工作流中插入一个“调试输出”节点，输入 {{payload}}，然后运行一次，检查输出结果是否为您期望发送的 JSON 数据。这是最直观的验证方式。

方法三：使用 Postman 等工具发送一次携带正确签名的请求，观察响应体。如果返回 {"status":"success","run_id":"xxx"}，则说明 Dify 已接受请求并启动了工作流，可以放心使用。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Dify中通过外部Webhooks接收系统事件通知的方法要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题