须知 —— Webhook 限制与系统行为

了解 finlight 如何处理 webhook 错误、重试和限制，有助于您构建更可靠的集成并有效管理您的配额。

错误处理与重试

重试逻辑

当 webhook 投递失败时，finlight 会自动重试请求：

重试计划：

• 第 1 次重试：在首次失败后立即进行
• 第 2 次重试
• 第 3 次重试

最大尝试次数：

• 每个 webhook 事件总共 3 次投递尝试
• 每次重试都使用相同的负载和标头
• 所有重试尝试都会记录在您的调用历史中

哪些情况会触发重试

以下情况会触发重试：

• HTTP 错误码 4xx 和 5xx 响应
• 网络超时（5 秒限制）
• 连接失败（DNS 错误、连接被拒绝）
• SSL/TLS 错误（证书问题）

哪些情况不会触发重试

以下情况不会重试：

• HTTP 2xx 响应（视为成功）
• 无效的 webhook 配置（格式错误的 URL）
• 已禁用的 webhook

自动禁用保护

连续失败跟踪

finlight 会跟踪连续的 webhook 失败，以保护您的配额并防止无休止的失败尝试。

工作原理：

1. 成功会重置计数器 —— 任何一次成功投递（HTTP 2xx）都会将失败计数器重置为 0
2. 失败会增加计数器 —— 每次投递失败都会增加连续失败计数
3. 达到 10 次时自动禁用 —— 连续失败 10 次后，webhook 会被自动禁用

自动禁用行为

何时触发自动禁用：

• 在所有重试尝试中连续 10 次投递失败
• webhook 状态从“已启用”变为“已禁用”
• 出现指示自动禁用的控制台通知
• 在手动重新启用之前不再进行任何 webhook 尝试

重要说明：

• 只有连续失败才会计入自动禁用
• 任何一次成功投递都会将计数器重置为 0
• 需要手动重新启用 —— webhook 不会自动启用
• 所有失败类型都会计入（超时、4xx、5xx 响应）

示例场景

场景 1：计数器重置

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

场景 2：自动禁用

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

恢复与重新启用

手动重新启用流程

重新启用的步骤：

1. 使用调用历史确定根本原因
2. 修复端点问题（认证、URL、服务器错误）
3. 通过编辑状态设置在 webhook 详情中重新启用 webhook
4. 使用控制台测试按钮手动测试 webhook
5. 监控初始投递以确认问题已解决

预防策略

避免自动禁用：

• 在您的端点中实现适当的错误处理
• 返回恰当的 HTTP 状态码
• 主动监控 webhook 健康状况
• 为 webhook 失败设置告警
• 在生产之前于开发环境中测试更改

配额管理

您可以在控制台的图表上查看您的用量。请注意，用量的记录会有延迟。

失败的请求会计入配额

重要： 所有 webhook 投递尝试都会计入您的订阅配额，包括失败的投递。

哪些会计入：

• 初始投递尝试 —— 计入配额
• 所有重试尝试 —— 每次重试单独计入
• 失败的投递 —— 仍会消耗配额
• 测试 webhook 请求 —— 也会计入配额

配额影响示例：

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

高效管理配额

最佳实践：

• 快速修复端点问题以尽量减少失败的重试
• 监控调用历史以发现失败模式
• 在生产中启用 webhook 之前充分测试
• 使用适当的错误处理以返回恰当的状态码

配额保护： 自动禁用功能通过停止向持续失败的端点投递，帮助防止配额浪费。

有关 webhook 设置指南，请参阅 webhooks 主文档。有关测试和调试，请查看测试指南。