什么是Webhook？

无抓取的抓取API可以在异步作业完成后将任务结果发送到配置的Webhook端点。

Webhook允许服务告诉您的应用程序某些事情发生了，而无需等待您的应用程序再次询问。任务服务可能报告完成，支付服务可能报告结算费用，或部署平台可能报告构建完成。生产者发起对消费者控制的URL的HTTP请求。您的应用程序接收消息，决定是否接受，然后更新自己的状态。

短定义掩盖了几个工程选择。事件可以在原始用户操作结束后到达，即使处理成功，网络确认也可能丢失。因此，有用的Webhook设计涵盖认证、存储、去重、排序和恢复。本指南介绍了从注册到接收的一个通知，并解释了接收方应该信任证据而不是假设的地方。

生产者、事件和接收方合同

三个角色让Webhook交换变得易于理解。生产者拥有事件，事件记录描述了发生的事情，接收方暴露可访问的端点。生产者需要一个端点URL，通常需要一个指定要发送哪些事件的订阅。接收方需要知道预期的请求方法、头、有效负载形状和确认响应。 HTTP语义规范 定义请求和响应框架；提供者合同提供事件意义。

想象一个由任务ID标识的抓取作业。提交可能在收集完成之前返回。稍后，完成消息可以携带该ID和状态。接收方使用该ID将事件与存储的作业记录连接。它不应该假设每个有效负载都嵌入完整的最终数据集；某些服务发送指针，而其他服务则包含结果。在提交时持久化原始任务ID，以便这个后续关联不依赖于猜测的URL或显示标签。

当前的 AI抓取器任务生命周期 记录一个可选的Webhook URL和推送的任务ID、状态、输入和可选的任务结果。这是一个具体的合同，而不是通用Webhook架构。为另一个产品构建的接收方必须检查该产品的文档。即使在一个平台内，两个事件系列也可以使用不同的字段名称和完成状态。

Webhook交付与轮询

轮询按计划请求服务状态。Webhook改变了第一步的方向：源在有相关事件时联系您的端点。这可以减少空检查，缩短您的工作流注意到变化的延迟。它还增加了一个公共接收方、网络交付的不确定性和新的安全工作。两种模式都不会使底层业务事件在两个独立操作的系统间实现事务性。

一个实用的架构通常结合了Webhook以快速反应和定期状态检查以进行调和。计划检查将本地作业与提供者的权威任务状态进行比较，并找到缺少的通知或本地处理错误。让检查保持狭窄：只查询本地状态尚未达到受信任终端状态的作业。接收方和调和者都应该调用同一个幂等状态转换函数，而不是创建两个冲突的路径。

选择取决于时间敏感性和提供者的功能。如果结果必须在完成后不久处理，并且提供者文档中包含回调，则Webhook非常有用。如果消费者没有可访问的HTTPS端点或提供者没有交付机制，则轮询可能更简单。对于交互式的来回消息，持久连接可能更合适。Webhook这个名称并不承诺任何特定的延迟或持久性。

如何安全地接受通知

将传入的HTTP请求视为不可信输入。首先限制其大小和方法，要求预期的路由，并仅解析文档化的媒体类型。然后应用提供者的身份验证方法。如果提供者对有效负载进行签名，则验证必须使用确切的原始字节和文档化的签名头，在JSON解析器更改表示之前。 标准Webhook规范 描述一个通用的签名事件模型，但生产者必须实际实现它，接收方才能依赖该模型。

签名检查回答签名密钥持有者是否生成了那些字节。它无法证明事件是新的，负载是否匹配您的订阅，或者任务是否属于您的帐户。检查时间戳或重放元数据，当提供者提供这些时；将任务ID映射到本地作业；验证必需字段和允许的状态转换。将密钥保存在受管的密钥存储中，并在您选择的验证方案要求比较消息认证值时使用恒定时间比较。

准确描述无废行为。文档化的AI抓取器生命周期建立了回调有效负载和HTTPS URL的要求，但它本身并没有建立此回调携带特定签名头。根据所选产品的当前交付合同构建接收器。如果该事件类别的身份验证详细信息未被记录，请咨询支持或仅在提供商明确支持该设计并且您的安全审查接受其暴露风险时，在接收器URL中使用应用程序控制的秘密。

收据、排队和幂等处理

HTTP处理程序应该完成足够的工作使收据持久，然后使用提供商文档中的成功响应进行确认。常见的顺序是验证请求、记录事件ID或任务ID以及原始有效负载和收据时间、入队处理作业，然后响应。请求路径中的长数据转换提高了生产者即使您的数据库更新最终成功也会看到超时的机会。这种模糊性是业务处理需要重复保护的原因。

从提供商合同中选择去重键。稳定的事件ID是理想的，特别是当它存在时。如果生产者仅暴露任务ID和终端状态，则从这些文档化的字段及订阅或账户范围构建一个应用程序密钥。围绕该密钥添加数据库唯一性约束。消费者可以接受相同的通知多次，同时只应用一次业务效果。不要依赖于在进程重启时消失的内存集合。

任务也可以在消息到达之前改变状态。例如，在单独的状态检查已标记作业完成后，可能会处理完成通知。转换函数应该比较当前状态和传入状态，并拒绝任何会将已完成作业向后移动的更改。存储原始有效负载和决策，以便操作员可以解释为何接受了一条消息、被视为重复而忽略或被拒绝为无效。

注册、失败和可观察性

仅注册您控制的接收器URL。保持路径的特定用途，避免将内部地址暴露为回调目标。允许任意用户注册webhook端点的应用程序如果访问私有网络目标可能会成为服务器端请求伪造渠道。在注册时验证方案和目标策略，并在交付发生时如果您的系统本身是生产者，则重新检查解析的地址。 OWASP SSRF指南 解释了与此风险相关的网络边界。

在消费者处记录交付证据：接收时间、提供者任务或事件标识符、提供的模式版本、身份验证决定、确认状态、队列ID和最终处理状态。排除不必要的操作的秘密和个人数据。仅表达“webhook成功”的仪表板无法区分HTTP交付和成功的下游存储。将这些测量分开，并在停滞的接受事件上发出警报。

在依赖工作流之前用无害事件测试它。确认接收器可以通过HTTPS访问，有效负载状态转换符合预期，格式错误的有效负载被拒绝，并且重复的交付不改变额外的业务状态。如果提供者可以为一个对象发送多个事件，则模拟乱序消息。这些检查在没有假设生产者保证顺序或正确交付的情况下测试接收器合同。

当webhook是错误的工具时

webhook适合于对另一个系统的重要离散变化。它不适合按需读取当前资源。如果用户打开仪表板并询问最新的账户余额，普通的API查询比等待过去的通知更清晰。webhook可能会发出余额已更改的信号，而API仍然是调和权威值的地方。

高流量事件流也可能需要一个孤立HTTP接收器不提供的中介特性，例如分区排序和按偏移量重放。一个webhook生产者可能会提供自己的交付日志，但那是提供商特定的功能，不是基本概念的一部分。使用满足事件量、延迟容忍度和恢复要求的最小机制。

对于无废作业，请保持回调与文档化的异步任务相连。 抓取API 是一个用于结构化网络数据的产品界面，而相关的 行为工作流指南 解释了为什么任务标识符和结果处理很重要。明确完成任务触发的本地操作，并保留审计该操作的状态查找路径。

结论

webhook是生产者与接收者之间的事件触发HTTP调用。可靠的单元是完整的合同：注册、经过身份验证的接收、持久确认、重复控制、状态转换和调和。在将接收器扩展到其他事件类别之前，从一个文档化事件和可测量的本地结果开始。