> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RBLTracker 告警集成

> 通过 Webhook 将 RBLTracker（Generator Labs）的黑名单收录、证书到期与异常、监控探针超时事件同步到 Flashduty On-call。

RBLTracker（Generator Labs）监控邮件服务器 IP 或域名是否被收录到 RBL 黑名单，也提供证书监控和监控探针（Agent）。通过它的 Webhook，可以把以下事件同步到 Flashduty On-call：

* 主机被收录到黑名单或被移出黑名单
* 证书临近到期、证书出现错误、证书指纹反复变化、证书被替换
* 监控探针停止上报

带有"触发/恢复"配对的事件对应同一条 Flashduty 告警：先触发，配对的恢复事件到达后告警恢复。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **RBLTracker**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **RBLTracker**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 RBLTracker 中配置

***

<Steps>
  <Step title="添加 Webhook">
    1. 登录 RBLTracker（Generator Labs）控制台，进入 **Development → Webhooks**，点击 **Add Webhook**
    2. **Display Name** 填写便于识别的名称，如 `Flashduty`
    3. **URL** 粘贴 Flashduty 集成的完整推送地址，地址中需包含 `integration_key`
    4. 在 **Events** 中勾选需要同步的事件（见下表），点击保存

    | 类别 | 事件 | 在 Flashduty 中的效果 |
    | :- | :- | :- |
    | RBL 监控 | `rbl.host.listed` | 触发或更新告警 |
    | RBL 监控 | `rbl.host.delisted` | 恢复告警 |
    | 证书监控 | `cert.expiration.trigger` | 触发或更新告警 |
    | 证书监控 | `cert.expiration.resolve` | 恢复告警 |
    | 证书监控 | `cert.error.trigger` | 触发或更新告警 |
    | 证书监控 | `cert.error.resolve` | 恢复告警；仍有未解决的错误时更新告警 |
    | 证书监控 | `cert.flapping` | 触发告警 |
    | 证书监控 | `cert.flapping.resolve` | 恢复告警 |
    | 证书监控 | `cert.changed` | 触发一条不会自动恢复的告警 |
    | 监控探针 | `agent.timeout` | 触发告警 |
    | 监控探针 | `agent.timeout.resolve` | 恢复告警 |

    <Warning>
      触发事件和对应的恢复事件必须一起勾选，否则告警不会恢复。例如只勾选 `rbl.host.listed` 而没有 `rbl.host.delisted`，主机被移出黑名单后 Flashduty 中的告警仍保持打开。
    </Warning>

    账单类事件（`billing.*`）和 `rbl.host.check.started`、`rbl.host.check.completed` 不需要勾选：Flashduty 收到后返回成功，但不会创建告警。
  </Step>

  <Step title="发送测试并验证">
    在 Webhooks 列表中点击目标 Webhook 的 **Send Test**，选择一个事件类型发送。RBLTracker 会显示响应状态码和耗时，返回 `200` 说明地址可达。

    Send Test 会用占位对象（主机 `Test Host`、地址 `127.0.0.2`，证书监控项 `example.com`，探针 `Test Agent`）发送所选事件，且每次发送的对象 SID 都是随机的。Flashduty 识别出这些占位对象后只返回成功，不创建告警。

    要验证完整生命周期，可以在 RBLTracker 中添加一台已知被收录的测试主机，确认 Flashduty 收到 `rbl.host.listed` 对应的活动告警，主机被移出黑名单后确认告警恢复。
  </Step>
</Steps>

## Alert Key

***

Flashduty 用 RBLTracker 事件中对象的 SID 作为 Alert Key，并按事件类别加前缀：

| 事件类别 | Alert Key | 来源字段 |
| :- | :- | :- |
| RBL 收录 / 移出 | `rbl:<host.sid>` | `host.sid` |
| 证书到期 | `cert-expiration:<monitor.sid>` | `monitor.sid` |
| 证书错误 | `cert-error:<monitor.sid>` | `monitor.sid` |
| 证书指纹反复变化 | `cert-flapping:<monitor.sid>` | `monitor.sid` |
| 探针超时 | `agent:<agent.sid>` | `agent.sid` |
| 证书被替换（`cert.changed`） | 由 `monitor.sid` 和 `new_fingerprint` 计算的摘要 | `monitor.sid`、`new_fingerprint` |

RBLTracker 官方 API 文档中，同一台主机的 `rbl.host.listed` 与 `rbl.host.delisted` 携带相同的 `host.sid`，证书事件携带 `monitor.sid`，探针事件携带 `agent.sid`。`cert.flapping` 在官方文档中只有文字描述，没有完整示例，Flashduty 按其他证书事件的结构读取 `monitor.sid`。

主机名称、命中的黑名单数量、检查 SID（`check_sid`）和事件 SID（`event_sid`）的变化都不会改变 Alert Key。缺少对应 SID 的事件会被拒绝。

## 状态和告警等级

***

告警状态由事件类型决定，恢复事件见上表。RBLTracker 不发送告警等级，Flashduty 按事件类型设置：

| 事件 | Flashduty 等级 | 说明 |
| :- | :- | :- |
| `rbl.host.listed` | Warning | 收录会影响邮件送达，但不是服务中断 |
| `cert.expiration.trigger` | 剩余天数 ≤ 5（含已过期）为 Critical；≤ 30 为 Warning；更多为 Info | RBLTracker 在剩余 60、30、15、5、0 天时各推送一次，同一告警的等级随之升级 |
| `cert.error.trigger` | 错误的 `severity` 为 `error` 或 `critical` 时 Critical，其他为 Warning | 多个错误取最高等级 |
| `cert.error.resolve` | 仍有 `current_errors` 时按剩余错误更新等级，全部解决后恢复 | 部分错误解决不会关闭告警 |
| `cert.flapping` | Warning | 一小时内证书指纹变化三次及以上 |
| `cert.changed` | Info | 证书未经续期被替换 |
| `agent.timeout` | Warning | 探针停止上报，监控出现盲区 |

## 一次性事件的自动关闭

***

`cert.changed` 是单次通知，RBLTracker 不会发送对应的恢复事件。同一监控项每次证书替换都会产生一条独立告警，这些告警不会自动恢复。请开启协作空间的[超时自动关闭](/zh/on-call/channel/create-edit)，建议设置为 **24 小时**。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `check` | 事件类别：`rbl_listing`、`cert_expiration`、`cert_error`、`cert_flapping`、`cert_changed`、`agent_timeout` |
| `resource` | 主机地址、监控项地址或探针名称 |
| `event_type` | 本次推送的事件类型 |
| `host_sid` / `host_name` | RBL 监控的主机 SID 与名称 |
| `host` | 主机地址（RBL）或监控项地址（证书） |
| `listed_total` | 主机当前被收录的黑名单数量 |
| `blocklists` | 收录该主机的黑名单名称 |
| `check_sid` | 触发本次事件的检查 SID |
| `monitor_sid` / `monitor_name` | 证书监控项的 SID 与名称 |
| `expiry_days` | 证书剩余天数，负数表示已过期 |
| `error_codes` | 证书错误代码 |
| `flap_count` / `stable_fingerprint` / `alt_fingerprint` | 指纹反复变化的次数与两个指纹 |
| `previous_fingerprint` / `new_fingerprint` | `cert.changed` 中替换前后的证书指纹 |
| `agent_sid` / `agent_name` | 探针 SID 与名称 |
| `timeout_minutes` | 探针的超时阈值（分钟） |
| `instances` | 超时的探针实例标识 |

## 推送与重试

***

RBLTracker 以 `application/json` POST 推送，Flashduty 返回 2xx 视为成功。推送失败（非 2xx、超时或连接错误）会在 30 秒和 2 分钟后各重试一次，重试使用相同的事件 SID，不会产生重复告警。连续失败达到 10、20、30 次时 RBLTracker 会分别暂停推送 1 小时、6 小时、1 天，达到 40 次会停用该 Webhook，需要在 **Development → Webhooks** 中重新启用。

RBLTracker 会在每次推送中带上 `X-Webhook-Signature` 签名头。Flashduty 通过推送地址中的 `integration_key` 鉴权，不校验该签名头。

## 排查问题

***

* **RBLTracker 显示推送失败**：确认 URL 完整且包含 `integration_key`，并在 **Send Test** 的结果中查看响应状态码
* **Flashduty 返回参数错误**：请求体必须是 RBLTracker 的 JSON 推送，缺少 `host.sid`、`monitor.sid` 或 `agent.sid` 的事件会被拒绝
* **告警没有恢复**：确认已同时勾选对应的恢复事件；`cert.error.resolve` 仅在 `current_errors` 为空时恢复告警；`cert.changed` 不会恢复，请开启超时自动关闭
* **主机仍被收录时告警多次更新**：API 文档称 `rbl.host.listed` 在检查发现主机被收录时推送，同一主机的多次推送合并到同一条告警
* **Webhook 被停用**：连续失败 40 次后 RBLTracker 会停用 Webhook，修复地址后在 **Development → Webhooks** 中重新启用

更多字段含义请参阅 [RBLTracker Webhooks](https://docs.generatorlabs.com/using-web-hooks/) 和 [Webhook API 参考](https://docs.generatorlabs.com/api/v4/)。