文 | 万涂幻象
大家好，我是万涂幻象，一名专注商业 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 框架搭的最简单的接收器，让你有个体感。
【代码示例】
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 创行社区知识库
更多精彩内容，关注钛媒体微信号 （ID：taimeiti），或者下载钛媒体 App
