Webhook 回调没收到？可能是 payload 超 25MB 被直接丢弃了

当 Webhook payload 超过 25MB 时，平台会直接丢弃请求且不会重试，导致事件彻底丢失而非延迟。

当回调迟迟未到：是网络波动还是数据超限？

若回调迟迟未到且数据量触碰 25MB 红线，通常是源头被直接截断，而非网络波动或服务器宕机导致的传输失败。

开发者在排查问题时，第一反应往往是网络抖动或服务器宕机。但事实可能更简单粗暴：如果负载包触碰到红线，请求在源头就被直接截断了。GitHub 等主流平台明确划定了这条线：Webhook payload的上限为 25 MB。一旦超出这个数值，系统不会尝试投递，也不会排队等待压缩，而是直接拒绝传输。

这种拒绝是主动且即时的。事件在内部已经触发，仓库状态也已变更，但包含该事件的 payload 大小被网关直接拦截。这意味着“事件发生”和“数据送达”之间存在一道不可逾越的物理屏障。很多团队误以为发送成功代表业务闭环，其实二者界限分明。你能看到请求发出，不代表接收方完成了处理；反之，没收到响应也不代表后端事务未提交。这并非偶发的网络抖动，而是基于容量限制的确定性规则。

这里存在一个常被混淆的语境：许多开发者将”Webhook 超时”等同于“网络问题”，却忽略了另一种可能性——发送端根本没把包发出去。在 GitHub 的架构逻辑中，25MB 是一个硬性阈值（Hard Limit），而非软性建议。当构建 Payload 的对象序列化完成并计算大小后，若发现超标，系统会在应用层直接终止该次 HTTP 请求的发起流程。这意味着，对于接收方而言，这不仅是一次失败的连接，而是一次彻底的“静默消失”。你甚至无法通过日志看到“连接超时”或“413 Payload Too Large”这样的标准 HTTP 错误码，因为连接从未建立。这种机制设计旨在保护接收方的带宽和存储资源，防止单个超大事件拖垮整个集群，但其副作用是让故障排查变得极度隐蔽。

为什么 Webhook 没收到不一定是没发生：被丢弃后的状态真相

未收到回调不等于事件未发生，底层记录可能已生成，仅因数据包过大触发硬性拦截机制而在发出前被静默丢弃。

当业务方发现某个关键事件没有触发回调时，直觉往往指向“系统出错”或“网络断了”。但在数据量极大的极端情况下，真相可能恰恰相反。底层事件已经成功触发并记录，只是巨大的数据包触发了平台的硬性拦截机制，导致请求在发出前就被直接丢弃^[1]。这意味着，未收到回调并不等同于事件未发生，更不意味着业务逻辑没有执行。

将“发送”与“完成”混为一谈，是许多系统在灾难面前失效的根源。我们需要厘清两个常被忽视的事实：发送方发出请求仅证明事件已触发，并不代表下游事务已提交；接收方返回 HTTP 200 响应，仅证明请求到达且代码运行了，也不代表数据库里的资金或库存已经最终落库。

在资金变动、派奖或余额同步等核心场景中，这种界限尤为致命。如果因为 payload 大小限制而直接丢弃请求，你的系统会陷入一种诡异的沉默——既没有收到通知，也没有任何报错提示。此时若简单地将“无回调”解读为“无交易”，就会导致严重的资损或数据不一致。

目前的证据主要源于官方文档对 25MB 上限的描述，尚无独立的第三方事故记录或测量数据进行交叉验证^[2][3]。但这并不妨碍我们建立一套基于风险控制的工程逻辑。既然无法完全依赖供应商的合同性保证来覆盖所有边界情况，就必须假设回调本身存在不可靠的可能。因此，正确的做法不是被动等待回调来确认结果，而是主动构建独立的业务状态确认机制。对于高价值操作，必须通过轮询查询接口、本地状态快照或与上游系统的对账日志来进行二次校验。只有当外部通知与内部状态相互印证时，才能判定业务真正闭环。

一个值得注意的工程细节是：不同平台对“大小”的计算方式可能存在微妙差异。 例如，某些平台可能计算的是原始 JSON 字符串的字节数，而另一些可能在序列化和压缩后计算。虽然 GitHub 文档明确指出 25MB 是硬性上限，但未明确说明是否包含 HTTP 头部的开销。在实际操作中，如果你的 Payload 接近 24MB，务必考虑到序列化过程中的元数据膨胀（如特殊字符转义、嵌套层级增加导致的长度增长）。因此，将安全阈值设定在 20-22MB 不仅是留有余地，更是为了应对不同序列化策略带来的不确定性。

如何区分网络故障还是 payload 超限导致回调丢失

payload 超限导致的丢失表现为静默无信号，无法像普通网络故障那样返回错误提示，需通过排查数据大小来区分原因。

当你的系统迟迟收不到预期的 Webhook 通知，第一反应往往是网络波动或服务器宕机。但事实可能更棘手：如果 payload 超过了 25 MB，平台会直接丢弃请求，连一次“失败”的信号都不会发回^[1]。这种静默丢失让排查变得异常困难，因为接收端看到的只是“无数据”，无法分辨是路断了还是货太重被拒之门外。

要厘清真相，不能仅靠猜测，必须建立一套基于日志和机制的验证流程。首先，检查服务端是否记录了完整的 HTTP 请求头与响应时间。如果是网络故障，通常会有连接超时、DNS 解析失败或 TCP 重传等底层报错；而 payload 超限导致的丢弃，往往表现为发送方根本没有发起请求，或者在应用层直接拦截。若你发现事件触发时间与预期回调到达时间存在巨大差异，且中间没有任何握手记录，这极可能是触发了 25 MB 的硬性上限^[1]。

其次，利用错误码特征进行辅助判断。虽然大 Payload 被丢弃时没有标准错误码返回，但你可以观察重试机制的行为模式。网络问题通常伴随指数退避的重试，最终会因多次失败而停止；而 payload 超限的情况，由于发送方认为“无需投递”，根本不会触发重试逻辑。对比这两者的行为差异，能帮你快速锁定是链路问题还是数据量问题。

为了彻底避免误判业务状态，防止因过度信任回调而导致资损，你必须设计备用查询接口。核心在于理解“事件触发不等于业务完成”这一语义^[1][2]。当回调缺失时，不要默认事件未发生，而是主动轮询业务状态接口。例如，通过调用订单查询 API 确认资金是否已变动，用确定性查询弥补不确定性回调的缺失^[3]。针对大 Payload 场景，最稳妥的策略是在源头进行预处理。如果已知数据量将超过限制，应在生成 payload 前采取截断关键信息或异步导出附件的策略。与其等待一个可能被静默丢弃的请求，不如提前将大数据拆解为可传输的小包，确保业务流的连续性。

具体行动建议： 立即在你的 CI/CD 流水线或事件生成器中加入一个前置校验步骤。在构建 Webhook Payload 之前，先计算其 JSON 序列化后的字节大小。如果预估大小超过 20MB（预留 20% 的安全缓冲），自动触发分流逻辑：将非核心的详细数据（如长文本描述、完整 diff 内容）写入临时文件，生成一个短链接（Short URL）放入 Payload 中，并在后续通过独立 API 供接收方按需拉取。这种“主从分离”的设计既能满足 25MB 的限制，又能保留数据的完整性，是目前处理大型事件最成熟的工程方案。

常见误区与应对策略对比表

FAQ: 关于 Webhook 回调丢失的常见疑问

Q: 如果 payload 刚好是 25MB，会被丢弃吗？ A: 通常边界值是严格的。如果达到或超过 25MB，绝大多数平台（如 GitHub）都会直接拒绝。建议预留缓冲空间，将目标控制在 20-22MB 以内以确保安全。

Q: 有没有办法让平台自动压缩大 Payload？ A: 目前主流平台不支持自动压缩。如果数据量过大，必须在应用层自行处理，例如只发送关键 ID 而非完整对象，或使用异步文件下载链接代替大文本块。

Q: 如何确定回调丢失是因为大小限制而不是其他原因？ A: 最可靠的方法是检查发送端的日志。如果发送端根本没有发出 HTTP 请求，或者在应用层就拦截了，那大概率是触发了大小限制。如果是网络问题，通常会看到连接建立的尝试但最终超时。

参考来源

1. Webhook events and payloads - GitHub Docs · https://docs.github.com/en/webhooks/webhook-events-and-payloads（A级）
2. At-Least-Once vs. Exactly-Once Webhook Delivery Guarantees · https://hookdeck.com/webhooks/guides/webhook-delivery-guarantees（B级）
3. Webhook Delivery Guarantees: Retries, HMAC & Dead Letters | Codelit.io · https://codelit.io/blog/api-webhooks-delivery-guarantee（B级）