Webhook简介

3 阅读2分钟

Webhook 就是“事件发生时,对方主动用 HTTP POST 推数据到你指定的 URL”,不需要你反复轮询。

它怎么工作

一个完整的 Webhook 流程通常有 4 步:

  1. 注册回调地址
    你在自己的服务里提供一个公开可访问的 URL,比如:
    your-app.com/webhook/pay…
    然后把这个 URL 配置到第三方平台,比如支付平台、GitHub、表单系统。

  2. 事件发生
    第三方系统里发生了你关心的事件,例如:支付成功、代码推送、订单创建、用户注册。

  3. 第三方发起 HTTP POST
    它会向你配置的 URL 发送一个 POST 请求,请求体通常是 JSON,里面包含事件类型和关键数据。

  4. 你接收并返回 200
    你的服务收到请求后,先验证来源,再处理业务,最后返回 200 OK,告诉对方“我收到了”。

一个简单请求长什么样

POST /webhook/payment HTTP/1.1 Host: your-app.com Content-Type: application/json X-Signature: sha256=abc123...

{ "event": "payment.succeeded", "order_id": "12345", "amount": 9900, "currency": "CNY" }

生产里怎么实现更安全

实现 Webhook 不能只写一个接口收数据,建议做到这几件事:

  • 验签名:用对方提供的 Secret 对请求体计算签名,确认请求确实来自可信系统。
  • 快速返回 200:接口只做校验和入队,不要把耗时业务放在接口里同步执行。
  • 异步处理:把事件放进队列,再由后台任务更新订单、发消息、触发工作流。
  • 去重:同一个事件可能会重试,用 event_id 防止重复处理。
  • 记录日志:保留每次回调的请求头、请求体、处理结果,方便排查。
  • 幂等处理:即使收到重复请求,也不会产生重复订单、重复通知。

常见场景

  • 支付回调:支付成功后通知你的订单系统。
  • CI/CD:GitHub 推送代码后触发构建。
  • 消息通知:表单提交后通知飞书、钉钉、Slack。
  • 订单状态变更:发货、退款、取消时同步给下游系统。

一句话总结:Webhook 就是把“我不断问你”改成“你有事就通知我”,实现方式是对方在事件触发时向你的 URL 发起带签名的 HTTP POST。

需要我帮你对比一下 Webhook 和 WebSocket 的区别,方便你做技术选型吗?