Webhook 故障排查

如果需要按错误现象快速定位原因，也可以直接查看Webhook 投递失败。

连接超时

检查：

• 目标域名是否可以从公网访问。
• 服务端是否在规定时间内返回响应。
• 防火墙、安全组或 WAF 是否拦截请求。
• DNS 是否能稳定解析。
• 服务是否因冷启动或数据库连接过慢而超时。

DNS 或 TLS 问题

检查目标域名解析、证书有效期、证书链和 TLS 配置。不要用本地地址、测试内网地址或仅在公司网络可访问的地址作为生产目标。

3xx、4xx 或 5xx

• 3xx：检查是否配置了跳转。建议直接使用最终 HTTPS 地址。
• 4xx：检查路由、Token、请求方法和服务端权限。
• 5xx：查看目标服务错误日志和 Response Body，确认应用异常或依赖服务故障。

Webhook 接收接口应尽快完成校验并返回结果。耗时较长的业务处理可以放入异步队列。

Token 校验失败

检查：

• 控制台 Token 与服务端配置是否一致。
• Authorization 请求头解析方式是否正确。
• 是否误把 Public API Key 当成 Bearer Token。
• Token 是否已经更新但服务端仍使用旧值。
• 是否有多个环境使用了不同配置。

不要在错误响应中返回完整 Token 或内部校验细节。

重复事件

使用 Delivery ID 或 Request ID 做幂等键。重复收到同一标识时，返回成功并跳过重复业务动作。特别是发券、扣款、修改账户状态等不可重复操作，必须在数据库层做唯一约束或状态检查。

重试和投递顺序

当前版本不会自动重试失败投递，也不保证跨事件的严格投递顺序。你的服务端应：

• 允许同一事件重复到达。
• 不依赖事件严格按发生顺序到达。
• 使用事件时间和业务状态判断是否可以处理。
• 对无法处理的 Payload 记录 Request ID 和 Delivery ID。
• 通过投递日志确认最终状态。

如果需要补偿失败事件，请在你的服务端保存 Delivery ID、Request ID 和处理状态，再根据业务规则发起补偿或人工重放。GEELAB 当前版本不会自动把失败任务放回队列。

不会发起 HTTP 的情况

以下情况会在平台发出请求前失败，因此你的目标 URL 不会收到请求：

• 目标地址解析到受限地址，或 URL 不符合安全规则。
• 平台暂时无法读取这条投递所需的事件内容。
• Webhook 数据无法解析、版本不支持或缺少必要内容。

这类结果会在投递日志中显示对应失败状态。若日志中没有可用的结果明细，请同时记录本地接收服务的日志，并提供 Delivery ID 或 Request ID 联系支持。