Webhook 是异步推送，重复通知和投递失败都属于链路常态。处理思路可以归纳为两条：接收端用事件 ID 或业务唯一键做幂等，重复事件直接返回成功；发送端按错误类型分级重试，超限后进入死信队列并告警。本文按链路方向、接入前提、字段与幂等键、重试策略、验证观测五个环节展开，给出可落地的配置与核对方法。
要点总览（TL;DR）
- Webhook 是异步推送，重复通知和投递失败属于链路常态，处理责任要分开：接收端负责幂等去重，发送端负责分级重试。
- 幂等键优先用事件 ID，业务唯一键作辅助；接收端在事务内先插入去重记录并置为处理中，再执行业务逻辑，重复事件直接返回成功。
- 重试按错误类型分级：超时、5xx 等可重试错误走指数退避并设最大次数；签名错误、4xx 参数错误等不可重试错误直接记录并告警。
- 超过重试上限的事件进入死信队列并通知负责人，人工核对业务数据后决定补发或标记忽略；死信量突增时需要对账。
- 验证要覆盖重复投递、人为制造 5xx、死信告警和日志核对，上线后持续观测投递成功率、重试率与死信量。
Webhook链路里数据往哪个方向走
研发平台 Webhook 的数据方向是单向推送：研发平台作为事件发送方，业务系统作为接收方。事件源是研发平台内的业务动作，例如工作项状态变更、评论新增、版本发布；投递由平台侧完成；接收、处理和回执由业务系统负责。理解这条方向线，才能把去重责任放在接收端、把重试责任放在发送端。
Webhook 与同步调用有本质区别。同步调用由业务系统主动发起请求并等待响应，调用方掌握节奏；Webhook 由研发平台在事件发生时主动推送，业务系统被动接收，双方通过 HTTP 请求完成一次交互。异步推送意味着发送方无法确认接收方何时处理完毕，网络抖动、接收端重启、处理超时都会让一次投递变成多次投递。
完整链路可以拆成五个环节，每个环节都有对应的责任方和可能的异常点：
| 环节 | 发生位置 | 责任方 | 可能的异常 |
|---|---|---|---|
| 事件产生 | 研发平台业务动作触发 | 研发平台 | 同一动作短时间多次触发，产生多条事件 |
| 投递 | 平台向回调地址发起 HTTP 请求 | 研发平台 | 网络超时、连接失败、接收端返回 5xx |
| 接收 | 业务系统入口服务 | 业务系统 | 请求体解析失败、签名校验不通过 |
| 处理 | 业务系统内部逻辑 | 业务系统 | 处理超时、数据库写入失败、下游依赖不可用 |
| 回执 | 业务系统返回 HTTP 响应 | 业务系统 | 处理成功但响应丢失，发送方判定失败并重试 |
重复通知主要来自两个位置：投递环节的发送方重试，以及回执环节的响应丢失。发送方在超时或收到 5xx 后会重新投递同一事件，接收方如果已经处理过，就会收到重复通知。失败则集中在投递、接收和处理三个环节，其中处理环节的失败最容易被忽略，因为接收方已经返回了成功响应，但业务逻辑实际没有完成。
接入前要确认的权限与前提
Webhook 配置涉及研发平台和业务系统两侧，接入前需要把认证、权限和网络条件逐项落实，避免上线后才发现回调地址不可达或密钥缺失。
回调地址的可达性与 HTTPS 要求。回调地址必须是业务系统对外可访问的 HTTPS 地址，证书在有效期内且域名与证书匹配。如果业务系统部署在内网，需要确认研发平台的出口网络能够访问该地址，必要时通过反向代理或网关暴露回调入口。回调地址不要带查询参数中的临时凭证，避免日志泄露。
签名密钥或 Token 的生成、保管与轮换。接收端需要能验证请求确实来自研发平台。常见做法是平台侧生成签名密钥，发送时对请求体加时间戳计算签名，接收端用同一密钥验签。密钥应存放在配置中心或密钥管理服务中，不写入代码仓库；轮换时保留新旧两把密钥的并行验证窗口，确认全部流量切换后再下线旧密钥。
研发平台侧创建 Webhook 所需的权限。创建和管理 Webhook 通常需要项目管理员或系统管理员角色，普通成员一般只能查看。接入前确认由谁持有该权限，以及配置变更是否需要审批。权限归属不清会导致回调地址变更时无人可操作。
接收端服务账号的最小权限。业务系统处理事件时使用的服务账号，只应具备写入去重表、更新业务状态所需的最小权限，不授予跨项目或管理级权限。事件处理逻辑与人工操作使用不同账号，便于审计和故障定位。
事件订阅范围与字段版本确认。研发平台通常支持按事件类型订阅，接入前明确需要哪些事件、每个事件包含哪些字段、字段是否有版本标识。订阅范围过宽会增加无效投递和重复处理压力，过窄则可能漏掉关键状态变更。字段版本需要在接收端做兼容解析，避免平台升级字段结构后解析失败。
事件字段与幂等键怎么设置
接收端处理事件的第一步是字段映射，第二步是幂等判断。幂等键的选择直接决定去重是否可靠，建议以事件 ID 为主键、业务唯一键为辅助，两者配合使用。
关键字段的用途如下：
- 事件 ID：发送方为每次事件生成的唯一标识，同一事件多次投递时保持不变，是去重的首选主键。
- 事件类型：标识事件语义，例如工作项创建、状态变更、评论新增，用于路由到不同的处理逻辑。
- 时间戳：事件产生时间，用于判断事件顺序和处理时效，也可作为乱序到达时的参考。
- 业务对象 ID：事件关联的业务实体标识，例如工作项 ID、项目 ID，用于定位业务数据和辅助去重。
去重表建议包含以下字段：事件 ID 作为唯一主键，业务对象 ID 和事件类型作为辅助索引，处理状态记录待处理、处理中、成功、失败，重试计数记录该事件被处理的次数，首次接收时间和最后更新时间用于排查时序问题。事件 ID 唯一约束由数据库保证，重复插入直接失败，接收端捕获唯一键冲突后返回成功。
处理顺序必须是先落库再处理。接收端收到请求后，先在事务内插入去重记录并将状态置为处理中，插入成功才执行业务逻辑，处理完成后更新状态为成功。如果先执行业务逻辑再记录，一旦记录失败，发送方重试时接收端无法判断该事件是否已处理，会造成重复执行。事务边界要覆盖去重记录插入和业务状态更新，确保两者同时成功或同时回滚。
同一事件多次到达时的判断逻辑：查询去重表中该事件 ID 的记录，状态为成功则直接返回成功，状态为处理中则返回成功并等待前一次处理完成，状态为失败则按重试策略重新处理或转入人工核对。业务唯一键作为辅助判断，用于事件 ID 缺失或平台未提供稳定事件 ID 的场景，此时用业务对象 ID 加事件类型加时间戳组合去重，但可靠性低于事件 ID。
字段版本变化时，接收端解析逻辑应保留对旧版本的兼容分支，新增字段忽略未知值，删除字段提供默认值。版本号随事件体一起传递，接收端按版本号选择解析器，避免平台升级导致处理中断。
失败重试与重复通知的处理策略
重试策略的核心是区分错误类型：可重试错误交给退避重试，不可重试错误直接终止并记录，避免无效重试放大问题。
| 错误类型 | 典型场景 | 处理方式 |
|---|---|---|
| 可重试 | 连接超时、读取超时、接收端返回 5xx、下游依赖暂时不可用 | 按指数退避重试，设置最大次数 |
| 不可重试 | 签名校验失败、4xx 参数错误、事件体格式错误、订阅已删除 | 记录错误详情，不重试，告警通知负责人 |
指数退避的设置思路是首次重试间隔较短，例如 30 秒，之后每次翻倍，上限控制在几分钟到十几分钟，最大重试次数根据业务时效要求设定，常见为 5 到 8 次。退避间隔要加随机抖动，避免大量事件在同一时刻集中重试造成接收端压力。最大次数不宜过大，超过业务可接受延迟的重试没有意义。
接收端快速返回成功、异步处理的取舍需要按处理耗时决定。处理逻辑在数百毫秒内完成时，同步处理并返回结果更简单；处理涉及外部调用或批量写入时，接收端应先完成去重落库，立即返回成功，再把事件放入内部队列异步处理。异步处理要求接收端自己维护处理状态和失败重试，不能依赖发送方重试来兜底。
超过重试上限后，事件进入死信队列并触发告警。死信记录应包含事件 ID、事件类型、业务对象 ID、失败原因、重试次数和最后失败时间。告警发送给集成负责人，由人工核对业务数据后决定补发或标记忽略。补发的触发条件包括：接收端故障已恢复、下游依赖已可用、字段解析问题已修复。对账的触发条件是死信量超过阈值或同一业务对象连续出现多条死信，此时需要比对研发平台侧事件记录和业务系统侧处理记录，确认是否有事件丢失。
在事件处理和状态跟踪环节，团队可以把死信核对、补发确认和集成方案文档放到 ONES 的工作项与知识库中管理：每条死信对应一个待核对工作项，处理结论和补发记录写入文档，便于后续审计。ONES 提供 API 接口用于集成企业系统，具体 Webhook 推送参数与重试配置以实际接入版本的接口文档为准。
怎样验证去重和重试真的生效
验证要覆盖去重、重试、退避、死信告警和持续观测五个方面，每项都有可执行的测试动作和判定标准。
| 验证项 | 测试动作 | 判定标准 |
|---|---|---|
| 幂等去重 | 用同一事件 ID 连续投递两次 | 业务数据只产生一条记录，第二次返回成功且无重复写入 |
| 重试与退避 | 接收端人为返回 5xx 或制造超时 | 发送方按递增间隔重试，日志中重试次数与间隔符合配置 |
| 不可重试错误 | 构造签名错误或参数缺失的请求 | 发送方不重试，错误被记录并告警 |
| 死信告警 | 让接收端持续失败直到超过最大次数 | 事件进入死信队列，告警按预期送达负责人 |
| 日志可核验 | 抽查若干事件的处理日志 | 事件 ID、重试次数、处理状态、时间戳齐全且可关联 |
上线后需要持续观测三类指标：投递成功率反映链路整体健康度，重试率反映接收端稳定性，死信量反映需要人工介入的事件规模。投递成功率持续下降通常指向接收端故障或网络问题；重试率上升说明接收端处理能力不足或下游依赖不稳定；死信量突增需要立即核对业务数据。指标按事件类型和接收端分别统计，便于定位问题范围。
验证完成后保留测试记录和观测看板，作为后续变更的基线。回调地址调整、签名密钥轮换、字段版本升级后，重新执行去重和重试验证，确认链路仍然闭环。
常见问题
接收端已经返回成功，但业务逻辑实际没执行完，这种情况怎么处理？
这是处理环节的失败，发送方看到成功响应后不会重试，事件就丢了。解决办法是把去重记录和业务状态更新放在同一个事务里：先插入去重记录并置为处理中，业务逻辑完成后更新为成功，事务提交才算处理完成。如果业务逻辑耗时较长，接收端应先落库并立即返回成功，再把事件放入内部队列异步处理，由接收端自己维护处理状态和失败重试，不能依赖发送方重试兜底。
平台没有提供稳定的事件 ID，幂等键还能怎么设计？
可以用业务对象 ID 加事件类型加时间戳组合成去重键，但可靠性低于事件 ID，因为时间戳精度和事件产生时序可能不一致。更稳妥的做法是让接收端在业务侧生成唯一键，例如业务对象 ID 加状态变更序号，并在去重表中对该组合加唯一约束。接入前应向平台确认事件体是否包含稳定标识，字段版本变化时同步调整解析逻辑。
重试次数和退避间隔设多少合适？
没有统一数值，取决于业务对延迟的容忍度。常见做法是首次重试间隔 30 秒左右，之后每次翻倍，上限控制在几分钟到十几分钟，最大重试次数 5 到 8 次。退避间隔要加随机抖动，避免大量事件在同一时刻集中重试压垮接收端。超过业务可接受延迟的重试没有意义，此时应尽早进入死信队列转人工处理。
死信队列里的事件，人工补发时要注意什么？
补发前先确认失败原因已经消除，例如接收端故障恢复、下游依赖可用、字段解析问题修复。补发时沿用原事件 ID，让接收端的幂等逻辑正常生效，避免重复写入业务数据。补发记录要写清事件 ID、补发时间、操作人和核对结论，便于后续审计。同一业务对象连续出现多条死信时，先比对研发平台侧事件记录和业务系统侧处理记录，确认是否有事件丢失再补发。
签名密钥轮换期间，接收端怎么保证不丢事件？
轮换时保留新旧两把密钥的并行验证窗口：接收端先尝试用新密钥验签，失败再用旧密钥验签，两者都通过才放行。确认全部流量切换到新密钥后，再下线旧密钥。轮换期间如果出现验签失败，属于不可重试错误，发送方不会重试，因此轮换要安排在低峰期并提前通知集成负责人，轮换后重新执行去重和重试验证。
