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

# Hyperping 告警集成

> 通过 Webhook 集成将 Hyperping 监控的宕机和恢复通知同步到 Flashduty On-call。

通过 Hyperping 的 Webhook 集成，把监控（Monitor）的宕机（`check.down`）和恢复（`check.up`）通知同步到 Flashduty On-call。每个 Hyperping 监控对应一条宕机告警：监控宕机时触发，监控恢复时关闭这条告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Hyperping 中配置

***

<Steps>
  <Step title="连接 Webhooks 集成">
    1. 登录 Hyperping，打开 [Integrations](https://app.hyperping.io/integrations) 页面
    2. 在 **Webhooks** 卡片上点击 **Connect**
    3. 将 Flashduty 集成的完整推送地址粘贴为 webhook URL 并保存

    Webhook 按项目（Project）配置，不是按监控配置：保存后项目下所有监控的宕机和恢复通知都会发往这个地址。
  </Step>

  <Step title="验证生命周期">
    Hyperping 官方建议用一个会返回错误的监控（例如指向一个返回 404 的页面）来验证。让监控真正宕机，确认 Flashduty 收到活动告警；再让监控恢复，确认原告警恢复。
  </Step>
</Steps>

Integrations 页面上的 Webhook 卡片标有 Pro，仅 Pro 及以上付费套餐可用；在免费试用期内点击该卡片会跳转到 Billing 页面。如果无法打开配置，请先升级套餐。

## 推送内容

***

Hyperping 以 JSON 格式 POST 事件，Flashduty 直接解析，无需配置模板：

| 字段 | 含义 | 在 Flashduty 中 |
| :- | :- | :- |
| `event` | `check.down` 或 `check.up` | 触发或恢复告警，标签 `event` |
| `check.monitorUuid` | 监控 ID | Alert Key，标签 `check_id` |
| `check.url` | 被监控地址 | 告警标题，标签 `resource` |
| `check.status` | 返回的 HTTP 状态码 | 标签 `status_code` |
| `check.downtime` | 宕机时长 | 标签 `downtime` |
| `check.pings[]` | 各检查区域的结果（区域、状态码、状态信息） | 写入描述；区域列表写入标签 `locations` |

告警标题使用被监控地址；地址为空时使用 `Hyperping monitor <监控 ID>`。

## Alert Key

***

使用 `check.monitorUuid` 作为 Alert Key。Hyperping 文档中 `check.down` 和 `check.up` 的示例使用同一个 `monitorUuid`，同一个监控的宕机和恢复通知落在同一条告警上；不同监控会生成不同的告警。修改地址、状态码、时间或检查区域不会改变 Alert Key。

请求中缺少 `check.monitorUuid` 时，Flashduty 会返回参数错误，因为无法可靠地把恢复通知关联到原告警。`event` 不是 `check.down` 或 `check.up` 的通知（例如 Hyperping 以后新增的事件类型）会被忽略并返回成功，不会创建告警。

## 状态和告警等级

***

Hyperping 的通知不区分告警等级，宕机按 Critical 处理。

| Hyperping `event` | Flashduty 状态或等级 |
| :- | :- |
| `check.down` | Critical |
| `check.up` | 恢复，原等级为 Critical |

`event` 为空或为其他值的请求会被拒绝，避免把无法判断状态的请求写入错误的告警生命周期。

## 常见问题

***

<AccordionGroup>
  <Accordion title="Webhook 测试按钮会创建告警吗？">
    Hyperping 在 webhook URL 输入框下方提供测试按钮，官方文档没有说明测试请求的内容。如果测试请求带有 `event` 和 `check.monitorUuid`，Flashduty 会把它当作一次普通通知处理并创建告警，请手动关闭；缺少这些字段时 Flashduty 返回参数错误，Hyperping 会显示推送失败，这不影响真实通知。
  </Accordion>

  <Accordion title="重复的宕机通知会产生多条告警吗？">
    不会。同一个监控的通知携带相同的 `monitorUuid`，会合并到同一条告警中。
  </Accordion>
</AccordionGroup>

## 排查问题

***

* **Hyperping 推送失败**：确认 webhook URL 是完整的推送地址，且包含 `integration_key`
* **Flashduty 返回参数错误**：确认请求为 Hyperping 的 JSON 通知，且 `event`、`check.monitorUuid` 非空
* **告警没有恢复**：确认监控恢复时仍使用同一个 Webhook；恢复通知与宕机通知的 `monitorUuid` 必须相同

字段说明请参阅 Hyperping 官方文档 [Webhooks](https://hyperping.com/docs/integrations/webhooks)。