> ## 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.

# Robotalp 告警集成

> 通过 Robotalp 的自定义 Webhook，把监控项的宕机和恢复同步到 Flashduty On-call。

Robotalp 是在线监控服务。监控项检测到宕机或恢复时，可以向 Robotalp 的自定义 Webhook 地址发送一份 JSON。把这个地址设为 Flashduty 的推送地址后，每次宕机对应一条 Flashduty 告警：宕机时触发 Critical 告警，同一次宕机恢复后告警自动恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Robotalp 中配置

***

<Steps>
  <Step title="添加自定义 Webhook 集成">
    1. 登录 Robotalp，点击右上角头像打开账号菜单，选择 **Integrations**
    2. 点击 **Add Integration**，选择 **Custom Webhook**
    3. 填写名称，在 URL 中填入 Flashduty 集成的完整推送地址（含 `integration_key`）
    4. 保存。无需添加自定义请求头

    <Warning>
      **Custom payload** 中填写的 JSON 会合并进每次发送的请求体。请不要在其中使用 `incident_id`、`status`、`monitor_id` 这些字段名，否则会覆盖 Robotalp 自带的字段，导致告警无法关联恢复。
    </Warning>
  </Step>

  <Step title="在监控项上启用该 Webhook">
    1. 编辑要监控的监控项（Robot，创建或编辑窗口均可），进入 **Alerts** 标签页
    2. 在 **Notification Preferences** 中打开刚创建的 Webhook
    3. 如果提供了通知频率选项，建议使用 **only once until resolved**（宕机期间只通知一次，恢复时再通知一次）

    每个监控项都需要单独启用，只创建集成不会发送任何通知。
  </Step>

  <Step title="验证">
    1. 在添加或编辑 Webhook 集成的表单里点击 **Test Connection**，Flashduty 会创建一条 Info 级别的测试告警，标题为 `Robotalp test notification`。它不会自动恢复，验证后请手动关闭
    2. 临时把监控项的地址改成一个会返回错误的地址（例如返回 HTTP 503），等待下一次检测，Flashduty 出现一条 Critical 告警
    3. 把地址改回正常值，等待下一次检测，原告警恢复

    检测间隔由监控项的设置决定，例如 1 分钟间隔下，宕机和恢复通知通常在约 1 分钟内到达。
  </Step>
</Steps>

## Alert Key

***

Flashduty 用请求体里的 `incident_id` 作为 Alert Key。Robotalp 对同一次宕机的宕机通知和恢复通知发送相同的 `incident_id`，我们在真实的 Robotalp 上验证过：同一个监控项先宕机、后恢复，两次推送的 `incident_id` 一致。

* 监控项名称、地址、错误信息、持续时间的变化都不会改变 Alert Key
* 同一个监控项两次不同的宕机，`incident_id` 不同，对应两条告警
* 缺少 `incident_id` 的请求会被拒绝，因为无法可靠关联后续恢复

## 状态和告警等级

***

Robotalp 的请求体没有告警等级字段，只有 `status`。

| Robotalp `status` | Flashduty 状态或等级 |
| :- | :- |
| `down` | Critical（网站宕机属于故障信号） |
| `up` | 恢复 |

其他值会被拒绝。恢复事件会带上 `resolved_at` 和 `downtime_seconds`，Flashduty 将它们和宕机原因 `result_message` 一起保存为标签。

## 排查问题

***

* **Flashduty 没有收到事件**：确认 Webhook 已在监控项的 **Notification Preferences** 中启用，且推送地址完整并包含 `integration_key`
* **告警没有恢复**：确认没有在 **Custom payload** 中覆盖 `incident_id` 或 `status`；如果监控项被暂停或删除，Robotalp 不会发送恢复通知，需要手动关闭告警，也可以在协作空间中开启告警自动关闭作为兜底
* **测试告警没有关闭**：Test Connection 的推送不会恢复，需手动关闭

更多说明请参阅 Robotalp 官方文档 [Webhook integration](https://docs.robotalp.com/guides/integrations/webhook)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.