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