文 | 万涂幻象
大家好，我是万涂幻象，一名专注商业 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 的 Flask 框架搭的最简单的接收器，让你有个体感。
【代码示例】
from flask import Flask, request, jsonify
# 初始化一个 Flask 应用
app = Flask(__name__)
# 创建一个路由，地址是 /webhook，只接受 POST 请求
@app.route('/webhook', methods=['POST'])
defhandle_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 举个例子，你看一眼就明白。
【代码示例】
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（关键步骤）：
- 官方地址: https://ngrok.com/download
- 下载：根据你的操作系统，下载对应的 Ngrok 压缩包并解压，你会得到一个 ngrok.exe (Windows) 或 ngrok (macOS/Linux) 文件。
- 获取令牌 (Authtoken)：访问 https://dashboard.ngrok.com/signup 注册一个免费账号（用 Github 或 Google 登录最快）。登录后，在左侧菜单找到 “Your Authtoken”，复制那一长串令牌字符。
- 认证（只需一次）：打开命令行，进入 ngrok 文件所在的目录，运行认证命令，把你的令牌粘贴在后面：
- Windows PowerShell: .\ngrok config add-authtoken <粘贴你的令牌>
- macOS/Linux/CMD: ngrok config add-authtoken <粘贴你的令牌> 这条命令会把令牌保存在本地，以后就不用再认证了。
下载 Postman：
- 官方地址: https://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 https://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 发送！
✅ 第四步：在 n8n 里查收并连接
- 发送成功后，你切回 n8n 的界面，会发现 Webhook 节点已经“亮了”，并成功捕获到了你从 Postman 发送的数据。
- 这就证明，你的 n8n “门铃”工作正常，并且成功收到了“包裹”。
- 现在，你可以从 Webhook 节点后面拖出一个新的节点，比如 Feishu (飞书)，在消息内容里引用上一步收到的数据（比如 {{$('Webhook').item.json.body}} ），实现自动化通知。
写在最后：Webhook 不是技术，是“连接器”的思维
回到最初那个“疙瘩”，就是如何给一个非底层的开发者讲明白 Webhook。
当我把这些东西翻来覆去地盘了一遍后，我发现，真正重要的，可能不是那些技术细节，而是一种思维方式的转变。
我们过去做系统，更多的是“索取”思维，是我需要数据了，我主动去 API 那里“拿”。
而 Webhook，代表的是一种“响应”思维，或者叫“订阅”思维。 我的系统就像一个雷达，时刻“监听”着外部世界的特定事件。一旦事件发生，它能立刻被动地“响应”，触发相应的业务逻辑。
从“主动索取”到“被动响应”，这正是现代自动化系统、乃至智能体设计的核心心法。
它让我们的系统从一个个孤岛，真正地连接成了有机的、能够实时互动的生态。
所以，别再被那些花里胡-哨的术语吓倒了。说白了，它就是一种约定，让系统之间能够更聪明、更高效地“通个气”。
当你理解了这一点，你就拿到了开启高级自动化和智能体世界的一把关键钥匙。
路还很长，我们都在路上，一起探索。
# 固定资源推荐
除了阅读文章，如果你希望有一个能随时提问、随时给答案的AI学习“陪练”，我把我积累的许多结构化知识，都放进了一个可以对话的AI知识库里。
很多朋友用过后觉得很方便，所以我把它的固定入口放在这里，希望能帮你更快地解决问题。
? 点击直达：万涂幻象AI创行社区知识库
