Webhooks：实时集成中被低估的英雄

Source: Dev.to

Webhooks：实时集成中被低估的英雄

作为一名多年来构建了无数集成的开发者，我逐渐意识到 webhook 是那类没有得到足够关注的概念之一。大家都在谈论 REST APIs、GraphQL 和微服务，但 webhook 呢？它们是默默支撑现代网络的大功臣，却很少登上聚光灯。

为什么 Webhooks 值得更多关注

把 webhook 想象成互联网的 “嘿，某件事发生了我会通知你”，而不是你不停地询问 “有什么新情况吗？现在呢？现在？”

• 技术定义：一种基于 HTTP 的回调函数，能够实现实时、事件驱动的应用间通信。
• 这意味着：你的应用不再反复 ping 某个服务（轮询），而是服务在有有趣事件发生的瞬间直接向你发送消息。

轮询 vs. Webhooks

个人故事

我记得第一次真正体会到 webhook 强大之处的情景。当时我在构建一个电商通知系统，最初的实现是每 30 秒检查一次是否有新订单。虽然能工作，但感觉……不对劲。服务器被大量请求压垮，99 % 的请求返回 *“没有新数据”。

随后我发现了 Stripe 的 webhook。不再是我的服务器不断询问 “有新付款吗？”，而是 Stripe 在每笔付款成功时直接 POST 到我的端点。于是服务器负载骤降 95 %，通知也变得瞬时。这一刻，我彻底明白了 webhook 的价值。

Webhook 生命周期

1. 向你集成的服务注册 webhook URL。

   https://myapp.com/webhooks/github

2. 事件发生（付款完成、PR 合并、用户注册）。
3. 提供方 构造负载——通常是 JSON——其中包含事件细节。
4. 提供方 向你注册的 URL 发送 HTTP POST。
5. 你的端点 处理数据 并返回 200 OK 以确认收到。

注意： 优秀的提供方会实现重试机制。如果你的端点宕机或返回错误，它们会再次尝试。例如，Stripe 会对失败的 webhook 重试最长 3 天。

常见陷阱与最佳实践

1. 验证传入的 Webhook

在我的 webhook 之旅的早期，我犯了一个新手错误：没有验证传入的 webhook。任何脚本小子都可以向我的端点发送伪造的 POST 请求，而我的应用会欣然处理它们。

我现在的做法（你也应该这样做）

• 签名验证 – 大多数提供商会使用 HMAC 对负载进行签名。使用共享密钥验证签名。

  import hmac
  import hashlib
  
  def verify_webhook(payload: str, signature: str, secret: str) -> bool:
      expected = hmac.new(
          secret.encode(),
          payload.encode(),
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(expected, signature)

• 仅使用 HTTPS – 切勿通过普通 HTTP 接收 webhook；数据通常是敏感的。

• 时间戳验证 – 确保 webhook 不会过旧，以防止重放攻击。

2. 幂等性是你的朋友

你可能会收到同一个 webhook 多次。将处理程序设计为 幂等——多次处理同一事件的效果应与仅处理一次相同。

3. 异步处理

1. 立即确认接收（return 200）。
2. 将实际工作排入队列（例如，推送到后台任务系统）。

提供商都有超时限制；你不想因此被超时。

4. 记录所有信息

当 webhook 无法正常工作时，日志是你最好的伙伴。记录：

• 原始负载
• 请求头
• 签名验证尝试

5. 使用真实的 Webhook 进行测试

大多数提供商允许你重新发送历史 webhook 或触发测试事件。开发过程中请充分利用这些功能。

实际案例

• Stripe – 付款现在由 webhook 驱动。无需轮询付款状态；Stripe 会在付款成功、失败或被争议时通知你。
• GitHub – webhook 在每次 push 时触发 CI 构建。无需计划任务检查新提交；代码推送后几秒即开始构建。
• Zendesk – 当工单状态变化时更新我们的 CRM。用实时更新取代了 5 分钟的 cron 任务。
• Industrial IoT – 来自 IoT 平台的 webhook 在温度阈值被突破时立即提醒我们，防止错过关键事件。

为什么 Webhook 被低估了

• 简洁性 – 没有像 OpenAPI 那样的花哨规范，也没有像 GraphQL 那样的类型系统。仅仅是普通的 HTTP POST 请求。
• 通用性 – 与语言无关，适用于所有环境。
• 高效性 – 在不使用 WebSockets 或 Server‑Sent Events 这类复杂方案的情况下解决实时问题。

要点

经过多年构建集成，我逐渐认识到 webhook 是我们工具箱中最务实的解决方案之一。它们并不光鲜亮丽，却极其高效。

下次编写轮询逻辑时，问问自己：

“Webhook 能更好地解决这个问题吗？”

十有八九，答案是 是。

轮到你了

你有没有关于 webhook 的难忘经历？我很想在评论中听到你的分享！

你对 webhook 有什么看法？

Webhook？在你的使用经验中它们被低估了吗，还是有它们出错的血泪教训？在下方留下评论吧！