Webhook 是一种由事件触发的 HTTP 回调机制：当支付、代码推送、订单创建等事件发生时，发送方主动向你预先配置的 URL 发出请求，通常是 POST，而不是等待你的系统反复查询。典型链路是“事件发生→发送请求→验证签名→保存并入队→快速返回 2xx→后台处理”。
它本身很简单，真正需要设计的是安全、幂等、重试、乱序、监控和故障恢复。
Webhook 到底是什么
“Hook”指在某个事件点触发动作。Webhook 通常是服务器到服务器的单向 HTTP 通知，也被称为 HTTP callback、反向 API 或异步 API 通知。GitHub 将其描述为：指定事件发生时，把通知发送到外部 Web 服务器（GitHub webhook 说明）。
Webhook 不是独立的传输协议，也没有全球统一的请求格式；它建立在 HTTP/HTTPS 和发送方定义的应用层约定之上。“实时”通常表示事件触发后低延迟发送，并不保证严格的实时性、只发送一次或按发生顺序到达。接收方常常还要调用发送方 API，取得完整或最新的资源状态。Svix 将其概括为用户定义的 HTTP callback（Svix）。
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
它是怎样工作的
- 接收方创建公网 endpoint，例如
https://example.com/webhooks/payment。 - 在服务商后台配置 URL、订阅事件和密钥。
- 服务商内部发生事件，例如支付成功或仓库 push。
- 服务商按自己的契约构造 HTTP 方法、请求头、payload、事件 ID、时间戳和签名。
- 请求发送到 endpoint；接收方使用未经修改的原始 body验证签名。
- 检查事件类型和事件 ID，将原始事件持久化或写入可靠队列。
- 安全接收后尽快返回服务商认可的
2xx，复杂业务交给 worker。 - 连接失败、超时或返回不成功状态时，服务商可能按自身策略重试。
你的系统 第三方服务
│ │
│── 注册 webhook URL ─────────────>│
│ │ 事件发生
│<──── POST + headers + payload ───│
│── 验证、保存、入队 ──────────────│
│────── 200/202 ──────────────────>│
│── worker 异步处理 │不同平台的 HTTP 方法、JSON 结构、签名头、超时、重试次数和成功响应范围都可能不同，必须以具体服务商文档为准。
一个 webhook 请求长什么样
POST /webhooks/payment HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: PaymentProvider/1.0
X-Event-Type: payment.succeeded
X-Event-Id: evt_12345
X-Signature: sha256=...
X-Timestamp: 1720000000
{
"id": "evt_12345",
"type": "payment.succeeded",
"created": 1720000000,
"data": {"payment_id": "pay_987", "amount": 4999, "currency": "usd"}
}POST 和 JSON 很常见，但都不是普遍保证。请求头名称、事件字段、签名输入和重试规则由供应商定义。事件 ID、业务对象 ID、某次交付尝试 ID 和网络请求 ID 也可能是不同值；重试通常应沿用原始事件 ID。
Webhook、API、轮询、WebSocket 和消息队列的区别
| 方式 | 谁发起 | 适合做什么 | 主要代价 |
|---|---|---|---|
| 普通 API | 客户端主动请求 | 查询、创建、更新资源 | 调用时机、限流和错误由客户端承担 |
| 轮询 | 客户端定时请求 | 服务商不支持 webhook、补偿和对账 | 无效请求多，延迟取决于间隔 |
| Webhook | 事件发送方主动请求 | 支付、订单、代码和订阅状态通知 | 重试、重复、乱序和公网安全 |
| WebSocket | 双方维护长连接 | 浏览器实时界面、聊天、双向状态 | 连接和扩缩容更复杂 |
| 消息队列 | 生产者写入、消费者确认 | 组织内部高吞吐事件流 | 基础设施和运维成本更高 |
Webhook 不是 API 的替代品：Webhook 告诉你“发生了什么”，API 让你获取或修改详细数据。常见稳健方案是 webhook 触发快速同步，再用定期 API 轮询补偿遗漏和对账。
最小可用接收器
接收器的顺序应是：读取原始 body、验证签名和时间戳、检查事件类型、以事件 ID 做幂等判断、保存或入队，然后返回成功。
Rank #2
@app.post("/webhooks/provider")
def receive_webhook(request):
raw_body = request.get_raw_body()
signature = request.headers.get("X-Signature")
if not verify_signature(raw_body, signature, WEBHOOK_SECRET):
return {"error": "invalid signature"}, 401
event = parse_json(raw_body)
event_id = event["id"]
if already_processed(event_id):
return {"status": "duplicate"}, 200
store_event(event_id, raw_body)
enqueue(event_id)
return {"status": "accepted"}, 202只有事件已经安全写入数据库或可靠队列后才返回成功。2xx通常表示“已接收”，不表示订单已创建、付款已入账或邮件已发出；202是否被某个服务商视为成功，也要查其文档。
安全接收：HTTPS 只是起点
验证签名而不是只看来源 IP
HTTPS 保护传输中的机密性和完整性，却不能单独证明请求来自某个服务商。攻击者仍可直接向公开 URL 发送伪造 POST。常见做法是共享密钥和 HMAC：
signature = HMAC-SHA256(secret, signed_content)服务端应从密钥管理系统读取 secret，按供应商规定拼接时间戳、事件 ID 和原始 body，重新计算签名，并以恒定时间比较。GitHub 推荐使用 X-Hub-Signature-256 和 HMAC-SHA256；旧的 X-Hub-Signature 是 HMAC-SHA1 兼容方案（GitHub 排查文档）。Slack、Stripe、Svix 的签名输入也不同，不能套用一套通用代码（Slack 签名验证；Svix Webhooks）。
保留原始 body
在验证前解析 JSON、重新序列化、改变空格或字段顺序、字符编码被中间件修改、代理改写 body，都会让签名失效。Stripe 和 GitHub 都把原始 payload 被修改列为常见原因（Stripe 签名排查）。
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →防止重放
攻击者可以截获合法请求后再次发送。让签名覆盖时间戳，拒绝过旧请求，并记录已处理事件 ID；时间窗口不能替代幂等。Stripe 官方库默认五分钟签名容忍窗口，并要求服务器时钟同步；Svix 也建议使用 NTP（Stripe Webhooks；Svix 接收指南）。
纵深防御
- 使用 HTTPS、请求体大小限制、速率限制、WAF 或 API gateway。
- secret 放入密钥管理系统，日志中遮蔽签名和敏感数据。
- IP 白名单只能作为额外过滤：IP 范围会变化，代理也可能隐藏来源，不能替代签名。
- 验证字段、事件类型和权限，避免把 webhook 变成开放转发或 SSRF 入口。
重试、重复、乱序和失败恢复
把重试当作正常情况
DNS、TCP/TLS、超时、4xx、5xx或发送方无法确认响应，都可能触发重试。Stripe live mode 会在最长三天内以指数退避自动重试，sandbox 策略不同；手动重发也不一定取消自动重试（Stripe Webhooks）。不要假设事件只发送一次。
用数据库保证幂等
CREATE TABLE processed_webhook_events (
provider VARCHAR(50) NOT NULL,
event_id VARCHAR(255) NOT NULL,
received_at TIMESTAMP NOT NULL,
payload_hash VARCHAR(255),
PRIMARY KEY (provider, event_id)
);以 provider + event_id 建立唯一约束。插入冲突时，将其视为已处理或处理中，不再次执行支付、退款、发货等不可逆操作，并通常返回服务商认可的 2xx。Standard Webhooks 规范也建议重试期间保持事件 ID 不变并将其作为幂等键（Standard Webhooks 规范）。不要只用内存集合记录已处理事件。
先确认，后异步处理
不要在 HTTP 请求中等待多个第三方 API、生成 PDF、发送邮件、大型数据库事务或人工审批。推荐“验证→保存原始事件→入队→返回 2xx→worker 处理”。Stripe 官方文档同样建议使用异步队列（Stripe Webhooks）。
处理乱序、积压和死信
网络和并行 worker 会造成乱序，例如 subscription.updated 先于 subscription.created 到达。不要依赖到达顺序；对同一资源使用版本号或更新时间，必要时通过 API 获取当前状态，并将同一资源路由到同一队列分区。
生产系统应保存原始 payload 和这些状态：received、verified、queued、processed、failed。同时记录重试次数、下次重试时间和 trace ID，设置有限次指数退避、死信队列、告警、手动 replay 及定期对账。这样即使服务商耗尽重试、队列失败或业务永久报错，也能恢复。
从零实现的检查清单
- 定义契约：写明事件类型、ID、时间、schema、版本、签名算法、超时、重试、顺序保证和保留期限。
- 建立 HTTPS endpoint：使用稳定 URL，配置连接/读取超时、大小限制和日志；不要把临时隧道当生产入口。
- 只订阅需要的事件：减少流量、数据暴露面和排查噪声。Stripe 与 GitHub 文档都建议按集成实际需求订阅（GitHub 排查文档）。
- 实现供应商专用验证：使用正确 header、算法、secret、时间戳和恒定时间比较。
- 持久化并入队：保存原始 body、必要 headers、provider、event ID、验证结果、接收时间和关联 ID。
- 明确响应：验证失败按供应商规则返回错误；临时故障返回
5xx以允许重试；安全接收和重复事件通常返回2xx。 - 建设 worker 与补偿：分类错误、重试、死信、replay、审计和完整同步。
常见故障的排查路径
完全收不到请求
- 确认 URL 可公网访问、DNS 和 TLS 证书正常。
- 确认路由匹配正确方法，且服务商后台启用了正确事件和环境。
- 检查 WAF、防火墙、网关、限流和服务商是否禁用了 endpoint。
- 查看服务商 delivery log 和服务器访问日志；GitHub 提供专门的 delivery 与 troubleshooting 文档（GitHub 排查文档）。
签名验证失败
- 核对测试/生产 secret、签名 header、算法和时间戳格式。
- 确认框架提供的是原始 body，代理没有改写 body 或 header。
- 同步服务器时钟，检查时间窗口和字符编码。
重复处理或持续重试
- 检查响应是否在服务商超时前返回，并确认返回码在其认可范围。
- 用数据库唯一键按 provider 和 event ID 幂等；不要把每次交付尝试当作新事件。
- 确认事件已写入持久化存储或队列后再返回成功，查看 worker、死信和重试日志。
本地测试和托管工具怎么选
| 场景 | 方向 | 适用边界 |
|---|---|---|
| 查看请求内容 | Webhook.site | 上手快；公共免费 URL 不适合支付、个人信息或令牌。文档见 官方文档。 |
| 让 Stripe/GitHub 访问 localhost | ngrok | 适合开发隧道和调试，不是高可用生产入口。 |
| 接收后编排多个 SaaS | Pipedream | 按计算时间 credits 计费；适合自动化，不一定适合核心高吞吐事务。 |
| 向客户提供 webhook 的 SaaS | Svix | 提供交付、重试、幂等、可观测性和管理能力；需评估数据托管。 |
| 路由、检查和 replay 中间层 | Hookdeck | 适合在应用与供应商之间增加保护层；已有成熟网关和队列的团队可能无需重复建设。 |
价格、额度和计划会变化。Webhook.site 的公共 URL 可能无需登录，知道 URL 的人可能看到数据；ngrok、Hookdeck、Svix 和 Pipedream 也应按地区、合规、数据驻留和可靠性要求评估。核心支付或订单系统通常应由自建 HTTPS ingress、数据库、队列、worker、死信和监控承担，而不是只依赖测试工具。
什么时候应该使用 Webhook
Webhook 很适合支付和订阅状态、Git push/pull request、CRM 联系人变化、表单提交、文件处理完成、邮件投递状态、身份验证和 SaaS 自动化。不应单独承担大型数据同步、严格顺序和一致性要求的跨系统事务、高吞吐内部事件流，或无法提供安全接入层的内网系统。对关键业务，使用 webhook 触发低延迟处理，再用 API 对账，是比单一机制更稳健的设计。
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →The Bottom Line
Webhook 只是一个由事件触发的 HTTP 请求；可靠的实现必须同时解决原始 body 签名验证、HTTPS、时间戳、幂等、快速确认、异步队列、重试、乱序、死信、replay 和对账。把它当作“只配置一个 URL”的功能，通常只能完成演示，不能支撑生产系统。
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
