Webhook入门

主要参考资料：
深入解析 Webhook：从原理到实践的全面指南: https://blog.csdn.net/weixin_43114209/article/details/144250750

简介

简单来说，Webhook 是一种“反向 API”或“事件通知回调”机制。它允许一个应用程序（服务 A）在特定事件发生时，自动向另一个应用程序（服务 B）指定的 URL（称为 Webhook URL 或端点）发送 HTTP 请求（通常是 POST 请求），通知服务 B 该事件的发生并传递相关数据。

核心概念与工作方式：

• 订阅事件：
  你（服务 B 的开发者或管理员）在服务 A 上注册一个你控制的 Webhook URL，并指定你感兴趣的事件类型（例如，“新订单创建”、“代码提交到仓库”、“支付成功”、“用户注册”等）。
• 事件发生：
  当服务 A 中发生了你订阅的特定事件时。
• 发送通知：
  服务 A 会主动构造一个 HTTP 请求（通常是 POST 请求），包含与该事件相关的数据（通常是 JSON 或 XML 格式），并将这个请求发送到你之前注册的 Webhook URL。
• 接收与处理：
  你的应用程序（运行在 Webhook URL 对应的服务器上）接收到这个 HTTP 请求。你的代码负责解析请求中的数据，并根据业务逻辑执行相应的操作（例如，更新数据库、发送通知、触发另一个工作流、调用另一个 API 等）。

Webhook 与传统 API 调用的区别

通信方式	被动（事件驱动）	主动（客户端发起请求）
数据流向	服务端主动发送数据	客户端主动请求数据
适用场景	实时事件通知	定期轮询或按需获取
资源消耗	更高效，无需频繁轮询	高资源占用，尤其是在高频轮询场景下

与轮询 (Polling) 的对比

理解 Webhook 的最好方式之一是与传统的 轮询 方式对比：

轮询 (Polling):

方式： 你的应用程序（服务 B）需要不断地、主动地向服务 A 发送请求（例如，每隔几秒或几分钟），询问：“有新事件发生吗？”

缺点：

• 效率低下： 大部分请求可能没有新数据（空轮询），浪费网络带宽和计算资源。
• 延迟高： 事件发生到你轮询到它之间有时间间隔，无法做到实时通知。
• 增加服务 A 负载： 服务 A 需要处理大量轮询请求，即使没有新事件。

Webhook:

方式： 服务 A 在事件发生时主动推送通知给你的应用程序（服务 B）。

优点：

• 实时性高： 事件发生后几乎立即通知。
• 效率高： 只在有实际事件时才发送请求，节省资源。
• 减轻服务 A 负载： 服务 A 不需要处理大量无意义的轮询请求。

典型工作流程

1. 配置：

在服务 A（事件源）中设置 Webhook URL（服务 B 的接收端点）和订阅的事件类型。

2. 触发：

服务 A 发生订阅事件。

3. 构造请求：

服务 A 生成包含事件数据（Payload）的 HTTP POST 请求。

4. 发送请求：

服务 A 将请求发送到配置的 Webhook URL。

5. 接收：

服务 B 的服务器（监听该 URL）接收到请求。

6. 验证（可选但推荐）：

身份验证：服务 B 验证请求确实来自服务 A（常用方法：API Key 认证、Basic Auth、OAuth、JWT 等）。签名验证：服务 B 使用预共享密钥验证请求体的签名（常用方法：HMAC），确保数据在传输过程中未被篡改。

7. 解析与处理：

服务 B 解析请求体（Payload），提取所需信息，执行业务逻辑（如更新数据库、发送邮件/Slack 消息、触发 CI/CD 等）。

8. 响应：

服务 B 向服务 A 返回一个 HTTP 状态码：

2xx (通常是 200 OK 或 202 Accepted)：表示成功接收并处理（或已接受处理）。
4xx (如 400 Bad Request, 401 Unauthorized)：表示请求有误或未授权，服务 A 可能会停止重试或记录错误。
5xx (如 500 Internal Server Error)：表示服务 B 处理时出错，服务 A 通常会进行重试。

9. 重试机制（通常由服务 A 实现）：

如果服务 B 没有返回 2xx 状态码，或者请求超时/失败，服务 A 通常会按照预定义的策略（如指数退避）进行若干次重试。