一篇搞懂：飞书多维表格、n8n、Dify 等自动化工作流里的 Webhook 到底是个啥

大家好，我是万涂幻象，一名专注商业 AI 智能体开发与企业系统落地的实践者。

长期聚焦定制化业务系统开发、多维表格定制、Prompt定制、智能体设计、自动化工作流构建、ComfyUI工作流与AI视频制作，致力于为各行各业打造能创造增长、构筑优势的AI落地解决方案。

在这里，持续分享前线实战案例与结构化落地方法，文末还有实用资源推荐，欢迎收藏~

上周六，我们雷打不动的在腾讯会议里做会员专属共学。

聊着聊着，一位朋友突然在聊天框里抛出了一个问题，当时的截图我还留着：

他问："我看 n8n 好像可以通过 webhook 来定时发送给飞书信息，啥时候专门出一个讲 webhook 的文章学习一下？"

这个问题，一下子把我心里那个"疙瘩"给勾出来了。

说真的，这玩意儿太常见了。你要做飞书多维表格的数据同步，做 Github 代码提交后的自动化部署，做 Dify 智能体里的工具调用...基本上，只要你想让两个独立的系统"实时"地通个气，就绕不开它。

但最要命的是，你去网上搜，出来的解释全是"HTTP 回调"、"事件驱动"、"被动通信机制"...

全是这种正确的废话。

这种解释就像一本写满了乐理的说明书，你看完了，还是不知道怎么把歌唱出来。

今天，我就用一线开发者的大白话，把这事儿给你彻底"盘"明白。不拽词儿，只求一件事：让

你看完就能跟别人讲清楚，上手就能用起来。

01｜忘掉那些"术语"，Webhook 就是个"系统门铃"

咱们先做个约定，把"回调"、"推送"、"HTTP"这些词全扔了。

你就想一个最简单的事。

假如你点了份外卖，想知道送到哪了。

传统的 API 方式是啥样的？

是你，每隔五分钟就得打开 App，刷新一下，问系统："到了吗？"、"现在到哪了？"、"还要多

久？"。

这叫"轮询"。你主动，系统被动。

说实话，这挺烦人的。你累，系统也累。大部分查询都是无效的，浪费资源。

那 Webhook 是啥样的？

是你下单后，该干啥干啥。外卖小哥一到你家楼下，他主动给你打电话："喂！你的外卖到了，下来拿一下！"

这就叫 Webhook。

你不用一遍遍去问。事情办妥了，对方会主动来"按门铃"通知你。

所以，Webhook 的本质，就是一个"反向"的 API**。**

API 是你问系统要数据。
Webhook 是系统主动给你送数据。

就这么简单。

它解决的核心问题，就是系统之间的实时通知。

比如，客户在你的网站上付了款，支付平台（微信、支付宝）就会通过 Webhook"按一下你服务器的门铃"，告诉你："嘿，订单号 XXX 付钱了，赶紧发货！"。

你不需要写个程序每秒钟都去问支付平台："那个订单付钱没？那个订单付钱没？"。

你看，是不是一下子就清爽了？

02｜光说不练假把式，这个"门铃"咋安装？

理解了原理，我们再往下走一步，看看这个"门铃"具体是怎么安装和工作的。

整个过程，就三步。

✅ 第一步：你得先告诉别人你家的"门牌号"

这个"门牌号"，在技术上叫回调 URL **(**Callback URL)。

说白了，它就是一个网址链接。

你得在"外卖平台"（比如 Github、飞书、或者任何支持 Webhook 的系统）上，找到配置的地方，把你这个 URL 填进去。

这个动作，本质上就是在告诉它："以后有事儿，往这个地址给我打电话就行。"

很多自动化工具，比如 n8n、Zapier，它们的 Webhook 触发器节点，一点开，就会自动生成一个独一无二的 URL，你复制过去用就行，极其方便。

✅ 第二步：说清楚，啥事儿才需要"按门铃"

你不能让别人鸡毛蒜皮的事都来通知你。

所以，在配置 URL 的时候，通常还会让你勾选需要订阅的"事件 (Event)"。

比如在 Github 里，你可以只勾选 push (代码推送) 事件。那只有当有人提交代码时，Github 才会来"按门铃"。别人创建 issue、发起 pull request，都跟你没关系，不会来烦你。

这个"订阅"机制很重要，能帮你过滤掉一堆不必要的垃圾信息。

✅ 第三步：接收"快递"，并签收

当事件发生后，对方系统就会朝你的 URL 地址，发送一个 HTTP POST 请求。

这个请求里，装着一个最重要的东西，叫 Payload (有效载荷)。

你可以把它理解成"快递包裹"里的具体物品清单。

它通常是个 JSON 格式的文本，里面清清楚楚地写着这次通知的所有信息。比如谁、在什么时间、干了什么事、相关的数据是啥。

你的服务器收到这个请求后，要干两件事：

立刻回复一个"收到"的信号。 在技术上，就是返回一个 200 OK 的状态码。这是礼貌，也是规则。你得告诉对方，"信我收到了，放心吧"。
拆开"包裹"，办正事。 把 Payload 里的数据拿出来，该更新数据库的更新数据库，该发通知的发通知。

🎯 硬核代码：用 Python 搭一个最简单的"门铃"接收器

理论说完了，有代码底子的朋友可能想看看具体怎么写。下面就是一个用 Python 的 Flask 框架搭的最简单的接收器，让你有个体感。

【代码示例】👇

python 复制代码

from flask import Flask, request, jsonify

# 初始化一个 Flask 应用
app = Flask(__name__)

# 创建一个路由，地址是 /webhook，只接受 POST 请求
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # 打印一下，看看请求头是啥样
    print("Headers: ", request.headers)
    
    # 获取发来的 JSON 数据（也就是那个"包裹"）
    data = request.get_json()
    
    # 打印一下"包裹"内容
    print("Received Webhook Payload: ", data)
    
    # 在这里，你可以加入自己的业务逻辑
    # 比如：把 data 存到数据库、发个飞书通知等等
    
    # 告诉对方"我收到了"，返回一个成功的 JSON 响应和 200 状态码
    return jsonify({"status": "success"}), 200

# 启动这个服务，让它在 5000 端口监听
if __name__ == '__main__':
    app.run(port=5000, debug=True)

【代码解读】👇

你看，核心代码就几行。它干的事，和我上面说的一模一样：指定一个地址 (/webhook)，等着别人用 POST 方法来"按门铃"，收到"包裹" (data ) 后，打印一下内容，最后回复一句"知道了" (200 OK)。

03｜想用好它，这几个"坑"你必须躲开

理论看着挺简单，但真正在生产环境里用起来，魔鬼全在细节里。作为开发者，我踩过不少坑，有几个是致命的，必须跟你说明白。

✅ 坑一：引狼入室------你得确定按门铃的是"谁"

Webhook 的 URL 是暴露在公网的。

这就意味着，任何人，只要知道了你这个地址，都能给你发个假请求，冒充 Github、冒充支付平台。

要是你收到假消息就发货、就改数据，那公司就得被你搞黄了。

所以，你必须用一套组合拳，来确保来的人是你等的人。

最基础也是最重要的一招，就是对"暗号"，也就是"签名验证 (Signature Verification)"。

在配置 Webhook 时，系统通常会给你一个密钥 (Secret)。对方在发通知时，会用这个密钥和"包裹"内容，通过一个加密算法（比如 HMAC-SHA256）算出一个"签名"，放在请求头里一起发过来。

你收到后，用同样的密钥和内容，用同样的算法，也算一遍。

最后比对一下两个"签名"一不一样。一样，就是自己人，放行。不一样，就是坏人，直接关门。

🎯 硬核代码：用 Python 实现"对暗号"逻辑

这个"对暗号"的过程，用代码写出来其实也不复杂。我拿 Python 举个例子，你看一眼就明白。

【代码示例】👇

ini 复制代码

import hmac
import hashlib

# 假设这是你和对方约定好的"暗号本"（密钥）
SECRET_KEY = "your_shared_secret_key"

def verify_signature(request):
    # 从请求头里拿到对方发来的"暗号"
    received_signature = request.headers.get('X-Hub-Signature') # 不同平台请求头字段可能不一样
    
    # 如果连暗号都没有，直接判定是坏人
    if not received_signature:
        return False
        
    # 获取原始的"包裹"内容（注意是bytes格式）
    payload_body = request.get_data()
    
    # 用我们的"暗号本"和同样的加密方法，自己算一遍"暗号"
    computed_signature = 'sha1=' + hmac.new(SECRET_KEY.encode(), payload_body, hashlib.sha1).hexdigest()
    
    # 用 hmac.compare_digest 来比较两个暗号，可以防止时序攻击，更安全
    return hmac.compare_digest(received_signature, computed_signature)

【代码解读】👇

核心逻辑就是"收到暗号、自己算一遍、再比较"。

但你以为这就完了？高手过招，还得留两手。对于金融支付这种打死不能出错的场景，你还得再加两道保险：

**保险一：认"门牌"（**IP 白名单）。 不仅要对上暗号，还得看看这人是不是从咱允许的几个"大院儿门口"进来的。像 Github 这种大平台，都会提供他们发请求的 IP 地址列表。你可以在服务器上设置，只接受这些 IP 的来访。
保险二：查"邮戳"（防重放攻击）。 坏人可能会把你合法的请求录下来，过几分钟再原封不动地发给你。怎么防？查请求里带的时间戳。如果一个请求的时间戳离现在已经超过了5分钟，管他暗号对不对，直接当成过期邮件扔掉。

记住，签名是基础，IP白名单和时间戳是高配。 任何没有签名验证的 Webhook，都等于是在裸奔。

✅ 坑二：一件事通知了八百遍------你得防止"健忘"

网络这玩意儿，非常不靠谱。

有时候你明明回复了"收到"（200 OK），但对方因为网络抖动没收到你的回复，它就会认为你挂了，然后过一会儿，又给你发一遍一模一样的通知。

这就是"消息重复"。

如果你没做处理，用户付了一次钱，你给他发了两次货。代码提交了一次，CI/CD 给你构建部署了两次。简直是灾难。

避坑方法：办事前先登记------保证"幂等性 (Idempotency)"。

这个词听着唬人，但做起来很简单。对方发来的"包裹"（Payload）里，通常会有一个独一-无二的 "事件ID (event_id)"。

你每次处理之前，先拿这个 ID 去你的数据库或者缓存里查一下，看是不是已经处理过了。

处理过： 直接回复"收到"，但啥也别干。
没处理过： 先把这个 ID 存起来，标记为"已处理"，然后再去干活。

这样一来，不管它来多少次重复的通知，你都只处理第一次。

✅ 坑三：活儿太慢，把"信使"给拖死了------你得学会"异步"

有的时候，你收到 Webhook 之后要干的活儿很复杂。

比如，要处理一堆数据，要调用好几个其他系统的 API，可能要花个几十秒甚至几分钟。

但对方的"耐心"是有限的，它发出请求后，可能等个 5 秒、10 秒没收到你的"200 OK"回复，就直接判定你超时失败了。

然后，它又会开始"重试"，给你再发一遍...这就陷入了恶性循环。

避坑方法：先把"信"收下，活儿交给"后台"慢慢干------异步处理。

正确的做法是，你的 Webhook 接收程序，绝对不要干任何耗时的活儿。

它的唯一任务，就是在验证完所有安全检查后，立刻把收到的"包裹"原封不动地扔进一个"消息队列"（比如 RabbitMQ、Redis List）里，然后马上回复"200 OK"，告诉对方"我收到了，你先走吧"。

然后，你有另外一个独立的、在后台运行的程序，慢慢地从"队列"里把这些"包裹"一个个拿出来，不慌不忙地处理。

这样就把"接收"和"处理"这两个步骤彻底分开了，互相不影响。你的 Webhook 接口能瞬间响应，永远不会超时。

04｜上手联调：本地跑通你的第一个 Webhook

光懂理论不行，真干起活来，你马上会遇到一个最头疼的问题：这玩意儿太难调试了！

我把一套绝对能跑通的、"从零到一"的完整联调步骤整理了出来，你严格按照这个顺序操作，保证没问题。

✅ 第一步：准备工具和代码

动手之前，先把工具和环境备齐，把准备工作做到位。

安装 Python 环境：

确保你的电脑上安装了 Python。如果没有，请先从 Python 官网下载安装。
打开命令行（Windows 叫 PowerShell 或 CMD，macOS 叫终端），输入 pip install Flask 并回车，安装我们需要的"接收器"框架。

下载并认证 Ngrok（关键步骤）：

官方地址 : ngrok.com/download

下载：根据你的操作系统，下载对应的 Ngrok 压缩包并解压，你会得到一个 ngrok.exe (Windows) 或 ngrok (macOS/Linux) 文件。

获取令牌 (Authtoken) ：访问 dashboard.ngrok.com/signup 注册一个免费账号（用 Github 或 Google 登录最快）。登录后，在左侧菜单找到 "Your Authtoken"，复制那一长串令牌字符。

认证（只需一次） ：打开命令行，进入 ngrok 文件所在的目录，运行认证命令，把你的令牌粘贴在后面：
- Windows PowerShell: .\ngrok config add-authtoken <粘贴你的令牌>
- macOS/Linux/CMD: ngrok config add-authtoken <粘贴你的令牌> 这条命令会把令牌保存在本地，以后就不用再认证了。

下载 Postman：

官方地址 : www.postman.com/downloads/

安装：这是个桌面 App，下载对应版本安装即可。建议注册免费账号，方便保存和同步你的测试请求。

✅ 第二步：创建并运行你的"接收器"程序

在你电脑上创建一个新文件夹（比如 webhook_test），在里面创建一个名为 app.py 的文件。

在你电脑上创建一个新文件夹（比如 webhook_test）。
关键操作 ：把刚才解压得到的 ngrok.exe 文件，复制到这个 webhook_test 文件夹里。
在 webhook_test 文件夹里，创建一个名为 app.py 的文件。
把下面这段代码完整地 复制粘贴到 app.py 文件里并保存。

from flask import Flask, request, jsonify

app = Flask(name)

@app.route('/webhook', methods=['POST']) def handle_webhook(): print("====== A Request Came In! ======") data = request.get_json() print("Received Payload: ", data) print("===============================\n") return jsonify({"status": "I got it!"}), 200

if name == 'main': app.run(port=5000)
打开第一个 命令行窗口，进入 webhook_test 文件夹，运行：python app.py

你会看到服务启动，并正在 5000 端口上监听。关键：让这个窗口一直开着，别关！

✅ 第三步：启动"隧道"并获取公网地址

重新打开一个全新的、第二个命令行窗口。
进入 webhook_test 文件夹（因为我们把 ngrok.exe 复制进来了）。
关键提醒 ：接下来这一步是在命令行里输入命令来运行 Ngrok，而不是去双击 ngrok.exe 文件。命令行工具的正确用法就是通过命令来调用它。
运行命令：
- Windows PowerShell: .\ngrok http 5000
- macOS/Linux/CMD: ngrok http 5000 （这里的 5000 必须和你 app.py 里的端口号一致）。

Ngrok 启动后，你的命令行窗口会显示类似下面这样的界面：

ngrok (Ctrl+C to quit)

Session Status online Account Your Name (Plan: Free) Forwarding your-string.ngrok-free.app -> http://localhost:5000
关键操作： 找到 Forwarding 这一行，完整复制 -> 箭头前面那个以 https:// 开头的网址。这就是你暴露在公网上的 Webhook URL。

✅ 第四步：发送测试"信号"

打开 Postman。

关键提醒 ：如果是第一次打开，请点击橙色的 **"**Switch to Workspaces" 按钮进入主界面。

在主界面上方，找到 "New" 按钮并点击，来新建一个请求。

新建一个请求，在请求方法下拉框里，把 GET 改成 POST。

在地址栏里，粘贴你上一步从 Ngrok 复制的公网 URL ，并在后面加上 /webhook。
- 完整的地址看起来像这样：https://<一串随机字符>.ngrok-free.dev/webhook
点击下方的 Body 标签，选择 raw，再在最右边的下拉框里选择 JSON。

在文本框里输入一些测试内容，比如：

{ "message": "Hello from Postman" }
点击右上角蓝色的 Send 按钮发送。

✅ 第五步：验证结果

现在，你应该能同时在两个地方看到成功的结果：

在 Postman 里： 你会收到一个 200 OK 的响应，内容是 {"status": "I got it!"}。

在你第一个命令行窗口（运行 app.py 的那个）： 你会看到打印出了 Received webhook data: {'message': 'Hello from Postman'} 的字样。

到这里，恭喜你，已经成功在本地跑通了第一个完整的 Webhook 流程！

05｜融会贯通：用 n8n 跑一个完整的****自动化流程

理论、代码、工具都盘完了，咱们最后回归到那个最初的问题场景："用 n8n 通过 webhook 发送飞书信息"。

这一下，你就能把所有知识点都串起来了。

✅ 第一步：在 n8n 里设置并"监听"

在 n8n 里新建一个工作流，第一个节点就选 Webhook。

打开节点设置，找到 HTTP Method，把它从默认的 GET 改成 POST。

关键操作 ：点击 "Listen for Test Event" 按钮。你会看到它变成了一个等待状态。这个动作，就相当于告诉 n8n："我准备好了，现在开始竖起耳朵等信号"。

✅ 第二步：复制"门牌号"

节点进入监听状态后，你会在 Webhook URLs 下看到一个 Test URL。点击它旁边的复制按钮。

✅ 第三步：用 Postman 模拟"按门铃"

现在咱们没有现成的系统来触发，正好把上一节的 Postman 派上用场。
打开 Postman，新建一个 POST 请求，把刚才复制的 n8n 的 Test URL 粘贴进去。

然后选择 Body -> raw -> JSON，输入一小段你想传递的 JSON 数据，比如：

{ "user": "WanTu", "action": "published article", "title": "Webhook explained in plain language" }
点击 Send 发送！