{
  "id": "webhook",
  "title": "Webhook",
  "lang": "zh-Hans",
  "source_lang": "en",
  "summary": "Webhook 是由事件触发的 HTTP 请求，可在应用程序之间传递信息，实现自动通知和系统集成。",
  "category": "computer-science",
  "subcategory": "software",
  "type": "concept",
  "aliases": [
    "Web钩子",
    "网络钩子",
    "HTTP回调"
  ],
  "generated_at": "2026-11-05",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/zh/webhook/",
  "translations": {
    "en": {
      "url": "https://aiwiki.page/en/webhook/",
      "json": "https://aiwiki.page/en/webhook.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "Webhook 是一种机制：当指定事件发生时，一个应用程序向另一个应用程序发送 超文本传输协议（HTTP）请求。接收方应用程序提供一个端点，通常以统一资源定位符（URL）标识，发送方应用程序向该端点传递事件信息。Webhook 常用于向外部系统通知付款完成、新的软件提交或客户记录更新等事件。它是基于 Web 技术的集成模式，而非某一种标准化协议。"
    },
    {
      "heading": "运行模型",
      "text": "Webhook 颠倒了常规信息请求的方向。在普通的应用程序编程接口（API）交互中，客户端向服务请求信息。而使用 Webhook 时，服务会在相关信息可用时，主动向预先配置的接收方发起请求。\n\n典型的交互包含五个阶段：\n\n- **注册：**接收方提供端点 URL，并选择希望接收的事件。配置可以通过网站、API 或订阅协议完成。\n- **事件产生：**源应用程序中的某项操作产生事件，例如订单状态发生变化。\n- **投递：**源应用程序向已注册的端点发送 HTTP 请求，通常使用 POST 方法。\n- **确认：**接收方返回 HTTP 响应，表明是否接受了请求。\n- **处理：**接收方解析事件并执行相应任务，可以在响应之前完成，也可以在响应之后异步执行。\n\n请求体通常采用 JSON，但某些实现也使用 XML、表单编码数据或其他表示形式。请求头可以携带事件类型、投递标识符、时间戳和身份认证信息。\n\n在投递过程中，发送服务充当 HTTP 客户端，即使它在面向自身用户时扮演的是服务器角色。这一区别遵循客户端—服务器模型：角色取决于具体的交互，而非应用程序的固定分类。"
    },
    {
      "heading": "事件与载荷",
      "text": "Webhook 载荷用于描述事件，或告知接收方有更多信息可供获取。常见的设计有两种：\n\n- **携带数据的通知：**载荷包含受影响资源的表示，例如订单及其更新后的状态。\n- **引用式通知：**载荷包含标识符或资源 URL，接收方通过 API 获取进一步的详细信息。\n\n携带数据的通知可以减少额外请求，并保留某次特定状态变化的信息。引用式通知可以缩小消息体积，并让接收方在自身访问权限范围内获取资源的当前状态。\n\n事件并不一定等同于资源的当前状态。例如，“订单已创建”通知到达时，订单可能已经被取消。载荷可能描述的是事件产生时的状态，而随后发起的 API 请求可能返回更新的状态。\n\n事件标识符、投递尝试标识符、资源标识符、时间戳和模式版本各有不同用途。尤其需要注意，多次投递尝试可能对应同一个逻辑事件。它们的确切含义取决于提供方的事件模型。"
    },
    {
      "heading": "与相关机制的比较",
      "text": "轮询\n\n采用轮询时，客户端会反复询问是否发生了变化。如果已经存在 API，这种方式实现起来很简单，但即使没有事件发生，频繁请求仍会消耗资源。降低请求频率则会增加通知延迟。\n\nWebhook 在事件发生并可供通知时主动发送通知，从而减少反复检查。不过，它要求接收方开放一个可访问的端点，或使用中间服务。轮询仍适用于核对数据、补获遗漏的变更，以及与不提供 Webhook 投递功能的服务进行集成。\n\n流式传输与消息传递\n\nWebhook 通常以独立的 HTTP 请求进行投递。它不同于 WebSocket协议所使用的持久连接；通过这种连接，应用程序可以交换消息，而不必为每条消息发起新的 HTTP 请求。\n\nWebhook 也不同于消息代理的订阅接口。消息代理可能提供持久保留、消费者偏移量、重放和顺序保证。Webhook 服务也可能提供其中一些功能，但使用 HTTP 本身并不会自动带来这些能力。\n\n在事件驱动架构中，Webhook 经常用于连接独立运营的服务。它也可以将事件送入内部队列或流处理系统，将外部通知的投递与下游处理分离。"
    },
    {
      "heading": "可靠性与投递语义",
      "text": "单次 HTTP 交互本身并不能保证事件预期的业务效果恰好发生一次。Webhook 同样面临分布式计算中的不确定性：接收方可能已经成功处理了请求，但发送方却未能收到确认。\n\n重试与重复投递\n\n在连接失败、超时或收到某些错误响应后，提供方通常会重试投递。不同重试策略在持续时间、频率以及对 HTTP 状态码的处理方式上各不相同。有些策略会逐步延长重试间隔，并常常加入随机变化，以避免大量重试同时发生。\n\n重试可能导致重复投递。因此，接收方通常采用具有幂等性的处理方式：反复接收同一个事件，与只接收一次产生相同的预期效果。这可能需要记录已处理的事件标识符，或使用应用程序特定的唯一性约束。\n\n如果记录事件和应用事件效果这两个操作可能各自独立失败，那么仅仅去重还不够。当这两个操作都作用于同一个数据库时，可以使用数据库事务来协调。涉及外部服务的效果可能需要额外协调，或由下游提供幂等性支持。\n\n“至少一次”投递通常允许重复；“至多一次”则允许事件遗漏。如果提供方没有明确约定，就不应假定具备其中任何一种属性。“恰好一次”的说法需要明确适用范围，不能仅凭一次成功的 HTTP 响应就推断成立。\n\n确认与持久化接收\n\n许多实现将 2xx 响应视为投递成功。这通常表示已接受请求，而不是所有下游操作均已完成。\n\n一种常见设计是先验证请求，将其持久化记录下来，然后返回响应，再执行耗时较长的工作。随后可通过队列（数据类型）向后台工作进程分发任务。如果在以任何持久化方式接收请求之前就返回成功，而接收方紧接着发生故障，就可能造成事件丢失。\n\n顺序与恢复\n\n并发投递、重试或网络延迟可能导致事件乱序到达。如果提供方提供资源版本和序列号，就可以借助这些信息识别过时的更新。仅凭时间戳并不总能确定可靠的全序关系。\n\n恢复机制可以包括投递日志、手动重新投递、保留的事件历史，以及定期与源 API 进行比对。因此，Webhook 通常被视为及时通知的手段，而非系统状态唯一的权威记录。"
    },
    {
      "heading": "安全性",
      "text": "公开的 Webhook 端点会接收来自自身信任边界之外的请求。身份认证、载荷验证和资源控制是需要分别处理的问题。\n\n传输与发送方验证\n\n超文本传输安全协议（HTTPS）通过传输层安全协议保护传输中的流量。在通常的配置下，它会向发送方验证接收服务器的身份；但不会自动向接收方证明请求是由哪个应用程序发送的。\n\n提供方可以使用共享密钥、持有者令牌、双向 TLS 或载荷签名来认证投递请求。一种常见方法是使用带密钥的消息认证码，例如 HMAC。尽管产品文档有时将其称为“签名”，但 HMAC 使用的是共享密钥，而不是公钥签名。\n\n验证通常依赖提供方指定的确切字节内容。在检查认证码之前，先解析 JSON 请求体再重新序列化，可能会改变这些字节，从而导致验证失败。\n\n重放与不可信输入\n\n通过正确身份认证的请求仍可能被重放。带签名的时间戳、接收时间窗口，以及对先前已接受事件标识符的跟踪，都可以限制重放，但前提是这些字段受到身份认证机制的保护。\n\n身份认证并不意味着每个载荷都可以安全处理。接收方仍需要进行模式检查、大小限制、授权检查，并防范处理成本过高或带有恶意的输入。过于详细的日志还可能泄露敏感载荷和凭据。\n\n端点注册风险\n\n允许任意目标 URL 的发送方可能面临服务器端请求伪造风险：攻击者可能试图诱使其访问内部服务或其他非预期目标。端点验证、网络限制以及审慎处理重定向，可以应对这一独立风险。\n\n端点验证质询可以证明对目标地址的控制权，但具体能提供何种保证，取决于验证协议。未经签名、仅声称请求来自某个提供方的字段，不能作为来源证明。"
    },
    {
      "heading": "应用与局限",
      "text": "Webhook 常用于连接支付系统、电子商务平台、客户管理软件、监控服务和版本控制平台。它可以启动自动化测试、更新订单履约系统、同步记录，或触发无服务器计算环境中的工作流。\n\n它的主要优点是通知延迟低、兼容常规 Web 基础设施，以及减少反复查询 API 的需要。其局限包括端点可用性问题、投递失败、事件重复或乱序，以及不同提供方各自特有的约定。\n\nWebhook 集成还依赖不断演变的接口约定：事件名称、载荷模式、重试策略和身份认证格式都可能发生变化。明确的版本管理、投递可观测性，以及文档中清楚说明的恢复行为，决定了集成在这些变化中能够保持多大程度的可靠性。"
    }
  ],
  "links": [
    "hypertext-transfer-protocol",
    "uniform-resource-locator",
    "application-programming-interface",
    "client-server-model",
    "event-driven-architecture",
    "stream-processing",
    "distributed-computing",
    "idempotence",
    "database-transaction",
    "queue-data-type",
    "authentication",
    "https",
    "transport-layer-security",
    "message-authentication-code",
    "version-control",
    "serverless-computing"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}