什么是 Webhook？一个 URL 就能让系统主动通知你

什么是 Webhook？

Webhook 是一种基于 HTTP 的事件通知机制：当源系统发生指定事件时，它会主动向你预先配置的 URL 发送请求，并把与事件有关的数据一并传过来。

简单说，Webhook 把“你不断去问有没有新数据”改成“有新数据时系统主动告诉你”。这个 URL 通常被称为 Webhook URL、回调地址或接收端点。

Webhook 常用于支付结果通知、代码仓库事件、表单提交、订单状态变化、聊天机器人告警和自动化工作流。它不是独立于 Web 的新协议，而是一种使用 HTTP、事件和回调地址组合出来的系统集成方式。

Webhook 的核心可以概括为四个要素：

1. 事件源：产生订单、支付、代码推送等事件的系统。
2. 订阅配置：接收方选择关心的事件，并登记一个 URL。
3. HTTP 请求：事件源通常用 POST 请求发送 JSON 数据。
4. 接收处理：接收方验证请求、记录事件，再触发业务动作。

因此，Webhook 不是“一个 URL 自动完成所有事情”，而是让两个系统通过这个 URL 建立事件通知通道。

Webhook 解决了什么问题？

Webhook 主要解决轮询造成的无效请求和通知延迟问题。轮询要求客户端定时查询状态，而 Webhook 只在事件发生时发送通知。

假设你有一个订单系统，希望新订单产生后立即通知客服。如果系统只提供查询 API，你可能需要每隔 5 秒请求一次：

GET /api/orders?status=new

即使一天中的大部分时间没有新订单，客户端仍然会发出请求，服务端也必须完成鉴权、查询和响应。按 5 秒一次计算，一个客户端每天会发出 17,280 次查询；接入方越多，这类空请求越多。

轮询频率还会制造一个直接取舍：

• 间隔越短，通知越及时，但网络、计算和限流压力越大。
• 间隔越长，资源消耗越低，但状态变化更晚才会被发现。
• 请求失败时，客户端还要判断是“没有变化”还是“查询失败”。

轮询并不是错误方案。需要定期获取完整状态、对方不支持 Webhook、接收端无法公开访问，或者业务允许分钟级延迟时，轮询仍然简单可靠。问题在于，用高频轮询处理低频事件通常不经济。

Webhook 为什么能减少无效请求？

Webhook 的解决思路是“不要问，事件发生时我来通知你”。接收方先登记 URL，之后保持等待；只有订阅事件发生，源系统才向该 URL 发出请求。

它很像餐厅的震动取餐器：点餐后不必反复去后厨询问，餐品准备好时设备自然提醒你。映射到系统中，餐品完成是事件，震动通知是 HTTP 请求，取餐器编号就是预先登记的接收地址。

Webhook 降低的是“发现变化”的成本。接收方在得到事件摘要后，仍然可以使用普通 API 查询最新完整数据。这种“Webhook 通知变化，API 获取或修改资源”的组合在真实系统中很常见。

Webhook 是怎么工作的？

一个完整的 Webhook 流程通常分为配置、触发、发送和处理四步。

1. 配置 URL：接收方提供一个可接收 HTTP 请求的地址，例如 https://example.com/webhooks/orders，并把它登记到服务提供方。
2. 事件触发：源系统发生已订阅事件，例如 order.created、payment.succeeded 或 push。
3. 构造并发送数据：源系统生成事件负载，通常以 JSON 作为请求体，通过 POST 发送到接收地址。
4. 验证与处理：接收方验证签名、检查事件是否处理过、保存事件，并触发入库、通知或工作流。

一次简化的支付通知可能长这样：

POST /webhooks/payments HTTP/1.1
Host: example.com
Content-Type: application/json
X-Webhook-Id: evt_01K123
X-Webhook-Timestamp: 1785398400
X-Webhook-Signature: sha256=9f86d081...

{
  "id": "evt_01K123",
  "type": "payment.succeeded",
  "created_at": "2026-07-30T10:00:00Z",
  "data": {
    "payment_id": "pay_1024",
    "order_id": "order_9527",
    "amount": 29900,
    "currency": "CNY"
  }
}

字段名称、请求头、签名算法和重试规则都由服务提供方定义，并不存在一套适用于所有平台的统一 Webhook 数据格式。接入前必须阅读对应平台文档。

Webhook 的数据包和接收地址有什么要求？

Webhook 负载通常包含事件类型、事件 ID、发生时间和关键业务数据，但数据是否“精简”取决于服务提供方。有的平台只发送资源 ID，有的平台会附带完整对象快照。

只发送资源 ID 的好处是负载小、数据模型稳定；代价是接收方还要调用 API 获取详情。发送完整快照能减少二次查询，但会增加传输量，也可能让接收方读到已过期的事件状态。

接收端点一般还要满足这些条件：

• 使用公网可访问的 HTTPS 地址。
• 能读取原始请求体并验证签名。
• 在提供方规定的超时时间内返回 2xx。
• 不把耗时业务全部放在同步请求中。
• 保存事件 ID，支持幂等处理和故障排查。

普通浏览器页面或手机 App 通常不适合直接接收 Webhook，因为它们没有稳定的公网地址，也不一定持续在线。开发阶段可以使用反向隧道把本地端口临时暴露到公网，但生产环境应使用稳定域名和受控服务。

Webhook 和轮询有什么区别？

Webhook 更适合低频变化、需要快速通知的事件；轮询更适合主动读取当前状态、定期同步或无法开放接收端点的场景。

在关键业务中，两者经常同时使用：Webhook 负责实时通知，定时查询负责对账和补偿。这样即使某次通知最终没有送达，系统仍能通过周期性核对恢复一致状态。

Webhook 如何验证请求来源？

生产环境不能只依赖一个“难猜的 URL”。更稳妥的做法是使用 HTTPS 和消息签名，验证请求确实来自服务方，并确认请求体没有被篡改。

常见签名流程如下：

1. 服务方和接收方预先保存同一个密钥。
2. 服务方对时间戳和原始请求体计算 HMAC，例如 HMAC-SHA256。
3. 服务方把时间戳和签名放入 HTTP 请求头。
4. 接收方使用相同密钥对收到的原始字节重新计算签名。
5. 接收方用常量时间比较函数校验签名，失败则拒绝请求。

除了签名，还应处理以下安全问题：

• 防重放：校验时间戳是否在允许窗口内，并记录已处理的事件 ID。
• 密钥管理：密钥放在服务端密钥存储或环境变量中，支持定期轮换，不能写进前端代码。
• 原始请求体：不要先解析并重新序列化 JSON，否则字节变化可能导致签名不匹配。
• 最小权限：Webhook 处理器只获得完成任务所需的权限。
• 端点保护：限制请求体大小、记录失败原因，并按平台能力配合 IP 范围校验。

签名验证只能证明消息真实性和完整性，不能替代业务校验。例如支付通知通过签名后，仍要检查商户号、币种、金额、订单归属和当前订单状态。

Webhook 为什么必须处理重试、重复和乱序？

Webhook 运行在网络之上，不能假设每个事件只到达一次、按顺序到达，或者第一次一定送达。不同平台的重试次数和退避策略不同，接收方应按“至少一次通知可能发生”来设计。

一个可靠的接收流程通常是：

1. 验证签名和时间戳。
2. 检查事件 ID 是否已经处理。
3. 将原始事件持久化或写入消息队列。
4. 尽快返回 2xx，避免服务方因超时再次投递。
5. 由后台任务执行耗时业务，并记录结果。
6. 失败时内部重试；超过阈值后进入死信队列或人工处理。

幂等是这里的关键。假设 payment.succeeded 被发送两次，接收方不能给同一订单重复发货或重复增加余额。常见做法是给事件 ID 建唯一约束，或让业务操作按订单状态进行条件更新。

事件还可能乱序到达，例如 subscription.updated 比更早发生的 subscription.created 先到。接收方可以比较事件版本或时间，必要时再调用 API 获取当前权威状态，而不是盲目按到达顺序覆盖数据。

GitHub Webhook 如何触发自动化？

GitHub Webhook 可以订阅仓库的 push、Pull Request、Issue 和 Release 等事件，并在事件发生后向指定端点发送通知。

以代码部署为例，流程可以是：

1. 在仓库中登记 CI/CD 服务的 Webhook URL。
2. 开发者向目标分支推送提交。
3. GitHub 发送包含仓库、分支和提交信息的事件。
4. 接收端验证 GitHub 签名，并检查仓库与分支是否符合规则。
5. CI/CD 系统拉取指定提交，执行测试、构建和部署。

实际生产环境不应让一个未经验证的 push 请求直接执行任意服务器命令。签名、仓库白名单、分支规则、固定构建流程和最小部署权限都不可省略。

支付系统为什么依赖 Webhook？

支付平台使用 Webhook 把支付成功、失败、退款和争议等异步结果通知商户服务器。商户应以服务端验证后的通知或主动查询结果为依据更新订单，而不是信任浏览器跳转页面。

用户完成付款后可能立即关闭页面，浏览器也可能断网，因此前端回跳不能保证抵达。支付 Webhook 则由支付平台直接请求商户服务器，更适合承载订单状态更新。

一个安全的支付处理器至少要完成：

• 验证平台签名与通知时间。
• 核对商户账号、订单号、金额和币种。
• 以幂等方式把订单从可转换状态更新为“已支付”。
• 把发货、开通权限等耗时动作交给后台任务。
• 定期调用支付查询或账单接口做对账。

Webhook 能缩短支付结果的感知时间，但它不是账务一致性的唯一保障。支付系统仍需要对账、补偿和人工异常处理机制。

聊天机器人如何使用 Webhook 推送告警？

Slack、飞书和企业微信等协作工具提供群机器人 Webhook。你的监控系统向机器人 URL 发送符合格式的消息，就能把服务器告警推送到指定群聊。

这种场景通常只需要三步：获取群机器人的 Webhook 地址、按平台格式构造消息、在异常发生时发送请求。它比完整接入聊天平台的用户授权、消息读取和通讯录 API 更轻量。

群机器人地址通常等同于发送凭证，泄露后可能被滥用。不要把地址提交到公开仓库或写进浏览器代码；还应配置关键词、签名、IP 白名单或频率限制等平台提供的保护能力。

Webhook 与事件驱动架构有什么关系？

Webhook 体现了事件驱动的核心思想：系统关注“发生了什么变化”，而不是持续查询“现在是什么状态”。

源系统只负责发布事件，接收系统决定如何处理。订单系统不必理解客服通知、数据分析和仓库流程的全部细节；它只需要声明“新订单已经创建”，下游服务各自响应。

但 Webhook 不等同于完整的消息队列。两者都能传递事件，却有不同侧重点：

当事件量大、需要长时间积压、多个消费者独立确认或严格控制顺序时，消息队列通常更合适。常见架构是先用 Webhook 接收外部事件，再写入内部消息队列处理。

Webhook 有哪些限制和常见误区？

Webhook 提高了通知实时性，但也把公网端点、可靠投递和安全验证的责任交给了接收方。

常见限制和误区包括：

1. 把 Webhook 当成保证送达的消息队列：提供方可能重试，但策略各不相同，关键业务仍需对账。
2. 收到请求就执行耗时任务：同步处理过久容易超时并触发重复投递，应先持久化再异步处理。
3. 只用密钥参数或隐藏 URL：URL 可能出现在日志中，应使用签名验证并避免在查询参数里放长期密钥。
4. 假设事件只会来一次：网络超时会让发送方重试，业务处理必须幂等。
5. 假设事件按发生顺序抵达：并行投递和重试会造成乱序，应比较版本或查询当前状态。
6. 把 Webhook 和 WebSocket 混为一谈：Webhook 是事件发生后的一次 HTTP 回调；WebSocket 是持续保持的双向连接。
7. 让 Webhook 负载成为永久事实来源：事件内容可能是快照，必要时应调用 API 获取当前权威状态。

Webhook 最适合做“及时告诉你发生了什么”，而不是独自承担所有数据同步和可靠消息职责。

常见问题

Webhook URL 是什么？

Webhook URL 是接收事件通知的 HTTP 地址。服务提供方在指定事件发生时，会向这个地址发送请求；接收方负责验证请求并处理事件。

Webhook 和 API 有什么区别？

API 通常由调用方主动请求，用来查询或修改资源；Webhook 通常由服务方在事件发生时主动回调，用来通知变化。两者经常配合使用：Webhook 通知资源有变化，API 提供当前完整数据和操作能力。

Webhook 一定使用 POST 和 JSON 吗？

不一定，但 POST 加 JSON 是最常见组合。具体 HTTP 方法、Content-Type、请求头和负载结构由服务提供方定义，接入时应以官方文档为准。

本地开发怎么接收 Webhook？

可以使用反向隧道把本地端口临时映射成公网 HTTPS 地址，再把该地址配置给服务方。测试时仍应验证签名，并注意临时地址变化和开发数据泄露风险。

Webhook 失败后会自动重试吗？

取决于服务提供方。很多平台会在超时或非 2xx 响应后重试，但次数、间隔、持续时间和是否保证顺序都不统一。接收方必须阅读平台规则，并自行准备幂等、监控和补偿机制。

Webhook 和 WebSocket 有什么区别？

Webhook 是服务端对服务端的一次性 HTTP 事件通知，不需要持续连接；WebSocket 是客户端与服务器之间长期保持的双向通信通道，更适合聊天、协作编辑和实时行情等高频交互。

总结：Webhook 是系统之间的事件门铃

Webhook 是一个接收 HTTP 请求的 URL，以及围绕这个 URL 建立的事件通知机制。它把主动查询变成被动接收，把持续轮询变成按事件触发。

它的实际价值有三点：更少的无效请求、更低的通知延迟，以及更松耦合的系统集成。要把 Webhook 用在生产环境，还必须做好签名验证、幂等、快速确认、异步处理、重试监控和定期对账。

下次看到平台设置页里的 “Webhook URL”，可以把它理解成一个事件门铃：关键事件发生时，对方主动来通知你，而不是让你不断敲门询问。

参考资料

• GitHub Docs：About webhooks
• Stripe Docs：Receive Stripe events in your webhook endpoint
• Slack API：Sending messages using incoming webhooks
• RFC 2104：HMAC: Keyed-Hashing for Message Authentication
• RFC 9110：HTTP Semantics