什么是Webhook？事件、交付、安全和设计

无抓取抓取API可以在异步抓取任务完成时向配置的Webhook URL发送HTTP POST请求。

什么是Webhook？

Webhook是一种机制，通过该机制，一个系统在事件发生后向另一个系统发送HTTP请求。接收应用程序注册一个端点URL，并通常选择事件类型，例如任务完成、发票支付、记录更新、部署完成或消息发送。当事件发生时，生产者使用事件数据和元数据调用该端点。

Webhook有时被描述为反向API调用。在普通的API交互中，消费者发起请求以读取或更改状态。使用Webhook时，生产者发起请求以通知消费者。接收的URL仍然是一个HTTP端点，实施必须应用普通的API安全性、验证、可用性和可观测性实践。

该 标准Webhook规范 收集了安全和可互操作Webhook交付的惯例。它涵盖有效载荷、事件元数据、签名和操作行为，而各个提供者仍然定义自己的事件类型和合同。

Webhook如何工作

1. 消费者注册一个端点。 注册可能在仪表板或API中进行，并通常将一个秘密与订阅关联。
2. 消费者选择事件。 狭义的订阅减少了不必要的流量和数据暴露。
3. 生产者记录事件。 域操作创建了一个具有稳定标识符的不可变事件或交付任务。
4. 生产者构建有效载荷。 它序列化事件类型、事件ID、发生时间、模式版本和相关数据。
5. 生产者签名交付。 签名覆盖原始主体和新鲜度元数据，遵循文档规定的方案。
6. 生产者发送HTTP请求。 使用JSON主体的POST请求是常见的，但合同决定方法和媒体类型。
7. 消费者验证并记录。 端点在接受事件之前检查传输、签名、时间戳、事件ID、模式和订阅。
8. 消费者确认。 在持久接受后返回文档中的成功状态，并通过队列或工人执行更长的处理。

Webhook有效载荷示例

一个小的事件信封可以将元数据与域数据分开：

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

所示的日期是一个说明性代码常量，而不是出版印章。事件ID支持去重，类型选择处理程序和模式，发生时间描述域事件，而版本控制有效负载演变。当签名方案使用它时，交付时间属于请求元数据。

不要假设Webhook主体包含完整的当前资源。一些生产者发送一个带有ID的薄通知，消费者随后调用API以获取授权的当前状态。其他人发送一个完整的事件快照。合同应声明有效载荷是否代表事件、事件后的资源或指针。

Webhook与轮询、API和WebSockets

重要系统通常结合模式。Webhook 提供快速通知，而定期对账过程将当前 API 状态与本地状态进行比较。Webhook 改善了延迟；对账检测间隙或策略变化，而不假设某一交付路径是完美的。

Webhook 签名的工作原理

共享密钥设计通常使用针对确切原始请求正文和元数据（例如交付时间戳和事件 ID）的密钥哈希。HMAC 是一种消息认证的标准结构，定义在 RFC 2104。其他提供者使用非对称签名，以便消费者可以使用公钥进行验证。

消费者必须遵循提供方的逐字算法。根据版本格式解析签名头，完美重建签名内容，计算预期值，并通过常量时间函数进行比较。仅在验证后，代码才应解析并信任 JSON 负载。

框架中间件在解析 JSON 并重新序列化时可能会破坏验证。尽管数据看似等价，空白字符、属性顺序、转义和数字格式可能发生变化。在常规正文解析前捕获原始字节，然后将验证过的字节传递给 JSON 解析器。

重放保护和幂等性

如果签名永不失效，则有效的旧 webhook 可以被恶意重放。因此，签名方案通常包括交付时间戳或其他新鲜度值。接收者仅接受小的文档时间窗口，并应保持时钟同步。时间戳检查补充而不是替代事件 ID 去重。

幂等性意味着多次处理相同逻辑事件会产生与一次处理相同的业务结果。将生产者的稳定事件 ID 存储在具有唯一性约束的表中，最好是在应用业务变更的同一事务中。标记事件“已见”而未进行业务更新，可能会导致工作丢失，如果过程在这两个操作之间停止。

一些操作自然是幂等的，例如将记录的状态设置为特定版本。其他操作，例如增加余额或发送消息，需要与事件 ID 绑定的幂等性记录。通过生产者的文档标识符去重，而不是通过哈希负载，因为两个合法事件可能拥有相同的主体。

排序和事件版本

交付顺序可能与发生顺序不同，因为事件可以通过不同的工作者、区域或队列传播。更新的到达可能在旧更新之前。除非生产者明确保证订阅的到达顺序，消费者不应将到达顺序视为业务顺序。

包括资源版本、序列或事件发生时间，并定义语义。仅在版本比本地版本更新时应用状态更新。对于表示不可变操作而不是状态快照的事件，保留由域建立的事件序列规则。

模式版本与资源版本是分开的。模式版本描述负载形状；资源版本描述特定实体的状态。保持概念区分可防止负载格式更改看起来像是更新的业务记录。

先确认，再通过队列处理

Webhook 端点应做有界工作：强制请求大小，验证签名，验证信封，保留事件 ID，存储或入队接受的事件，并返回文档成功响应。慢速数据库连接、外部 API 调用、文件生成和电子邮件发送应放在工作者中。

可靠的接受是重要的。在事件记录之前返回成功可能会导致丢失。如果在响应之前等待每个下游操作，可能会导致生产者保持连接，并在端点超过响应截止时间时导致重复交付。

队列消息应包含验证的事件、订阅上下文和安全的追踪标识符。用于签名验证的密钥不应包含在队列负载中。

端点注册安全性

如果用户可以注册任意的 webhook URL，则生产者成为根据用户输入操作的 HTTP 客户端。系统必须防止服务器端请求伪造。 OWASP SSRF 防护备忘单 描述允许列表和网络层控制。

对公共端点要求 HTTPS，解析和验证目的地，阻止回环、本地链接、私有、元数据和内部服务范围，并根据所选策略在重定向和 DNS 解析后再次应用检查。限制端口、方法、响应字节、连接时间和重定向行为。

在注册期间通过挑战或签名握手验证端点所有权。将 webhook 响应主体视为不可信，不要通过交付错误消息暴露内部网络细节。

常见的 Webhook 用例

可观察性和操作

跟踪事件ID、订阅ID、事件类型、模式版本、接收时间、验证决策、确认状态、处理状态和安全关联标识符。不要记录签名秘密、完整的授权标头或敏感有效负载字段。

测量接受延迟、队列延迟、处理持续时间、重复率、签名失败、无效模式、陈旧时间戳和排序冲突。将生产者交付健康与消费者业务处理健康分开，以便在后续失败的已接受事件不会消失在一般成功指标中。

提供一个可控的管理视图，可以通过事件ID进行搜索并展示编辑过的交付历史。运营团队需要足够的证据来诊断丢失的状态变化，而不暴露凭据或完整的敏感内容。

Webhook设计清单

1. 定义稳定的事件类型和ID。 记录有效负载是事件、快照还是指针。
2. 为模式版本管理。 声明新可选字段和事件修订的兼容性规则。
3. 对原始字节和新鲜度元数据进行签名。 公布确切的验证步骤并支持秘密替换。
4. 强制执行端点安全。 验证所有权并阻止SSRF目的地。
5. 以幂等的方式接受。 使用唯一的事件ID和事务安全的去重记录。
6. 在持久接受后确认。 将较长的工作移到队列中。
7. 预期重复和重新排序。 使用资源版本和对账，而不是到达顺序假设。
8. 编辑可观察性数据。 将秘密和敏感有效负载字段排除在日志和支持工具之外。

结论

Webhook将事件转换为HTTP通知，为集成提供低延迟更新，而无需不断轮询。HTTP调用是简单的部分。生产设计验证原始体签名，强制执行新鲜度，按事件ID去重，处理重新排序，仅在持久接受后确认，通过队列处理，保护端点注册免受SSRF，并进行重要状态对账。这些控制将回调转变为可靠的集成边界。