Webhook 就是“事件发生时,对方主动用 HTTP POST 推数据到你指定的 URL”,不需要你反复轮询。
它怎么工作
一个完整的 Webhook 流程通常有 4 步:
-
注册回调地址
你在自己的服务里提供一个公开可访问的 URL,比如:
your-app.com/webhook/pay…
然后把这个 URL 配置到第三方平台,比如支付平台、GitHub、表单系统。 -
事件发生
第三方系统里发生了你关心的事件,例如:支付成功、代码推送、订单创建、用户注册。 -
第三方发起 HTTP POST
它会向你配置的 URL 发送一个 POST 请求,请求体通常是 JSON,里面包含事件类型和关键数据。 -
你接收并返回 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 的区别,方便你做技术选型吗?