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

# Statuspal 告警集成

> 通过 Statuspal Webhook，把状态页事件（Incident）和 Statuspal 监控的服务上下线同步到 Flashduty On-call。

通过 Statuspal 的出站 Webhook，把状态页上的变化同步到 Flashduty On-call：

* 在 Statuspal 状态页上创建事件（Incident）时触发一条告警，事件结束或被删除时这条告警自动恢复
* 开启了 Statuspal 内置监控的服务变为 `down` 时触发一条告警，变回 `up` 时这条告警自动恢复

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Statuspal 中

***

<Steps>
  <Step title="新建 Webhook">
    1. 以管理员身份登录 Statuspal，进入要接入的状态页的管理后台
    2. 点击左侧菜单 **Webhooks**，再点击 **New Webhook**
  </Step>

  <Step title="填写推送地址和事件">
    1. **URL**：粘贴 Flashduty 集成的完整推送地址（包含 `integration_key`）
    2. **Events**：勾选以下事件
       * `incident.created`
       * `incident.updated`
       * `incident.deleted`
       * `service.monitored_status.updated`（仅在服务开启了 Statuspal 内置监控时会推送）
    3. 点击 **Create**

    每个状态页的 Webhook 单独配置。多个状态页可以推送到同一个集成，也可以各建一个集成，方便按集成设置路由。
  </Step>

  <Step title="验证">
    创建后点击 **Send test request**，Statuspal 会在页面上显示 Flashduty 返回的结果。Statuspal 没有公开测试请求的内容：如果测试请求在 Flashduty 中生成了一条告警，请手动关闭它。

    也可以用真实事件验证：在状态页上创建一个事件，Flashduty 中出现一条 Warning 告警；把事件标记为已解决（Resolve），这条告警恢复。
  </Step>
</Steps>

## 推送内容

***

Statuspal 推送 JSON，`event` 字段是事件类型，`data.object` 是对应的事件或服务：

**事件（`incident.created`、`incident.updated`、`incident.deleted`）**

| 字段 | 说明 | 在 Flashduty 中的用途 |
| :- | :- | :- |
| `data.object.id` | 事件 ID | Alert Key，标签 `incident_id` |
| `data.object.l_title` | 各语言的事件标题 | 告警标题（优先取英文，没有英文时取第一个；两者都没有时取 `data.object.title`） |
| `data.object.ends_at` | 事件结束时间 | 有值时恢复告警，标签 `ends_at` |
| `data.object.starts_at` | 事件开始时间 | 标签 `starts_at` |
| `data.object.service_ids` | 受影响的服务 ID | 标签 `service_ids`（逗号分隔） |

**服务监控状态（`service.monitored_status.updated`）**

| 字段 | 说明 | 在 Flashduty 中的用途 |
| :- | :- | :- |
| `data.object.id` | 服务 ID | Alert Key，标签 `service_id` |
| `data.object.name` | 服务名称 | 告警标题，标签 `service` |
| `data.monitored_status` | 监控状态，`up` 或 `down` | 告警状态，标签 `monitored_status` |
| `data.object.parent_id` | 所属服务组 ID | 标签 `parent_id` |
| `data.object.current_incident_type` | 服务当前的事件类型 | 标签 `current_incident_type` |

服务告警的标题形如 `API is down`。每条告警还带有标签 `source=statuspal` 和 `event`（推送的事件类型）。

## Alert Key

***

* 事件：事件 ID。同一事件从创建、更新到结束的每次推送落在同一条告警上
* 服务：服务 ID。同一服务从 `down` 到 `up` 的推送落在同一条告警上

事件告警和服务告警互不影响：服务下线后 Statuspal 自动创建事件时，会同时产生一条服务告警和一条事件告警，可以用协作空间的[告警聚合](/zh/on-call/channel/noise-reduction)把它们合并到同一个故障。修改事件标题或服务名称不会改变 Alert Key。

## 状态和告警等级

***

Statuspal 的推送内容不包含事件的类型（major、minor）或严重程度，所以事件告警统一为 Warning。

| Statuspal 推送 | Flashduty 状态或等级 |
| :- | :- |
| `incident.created`、`incident.updated`，`ends_at` 为空 | 触发或更新告警，Warning |
| `incident.updated`，`ends_at` 有值 | 恢复 |
| `incident.deleted` | 恢复 |
| `service.monitored_status.updated`，`down` | 触发告警，Critical |
| `service.monitored_status.updated`，`up` | 恢复 |
| `monitored_status` 为其他值 | 返回参数错误 |
| 其他事件类型 | 返回成功，不生成告警 |

计划维护（Maintenance）创建时就带有结束时间，Flashduty 把它的推送当作恢复处理；没有对应的触发告警，所以不会生成告警。

## 常见问题

***

<AccordionGroup>
  <Accordion title="事件处于 Monitoring 状态时告警会恢复吗？">
    不会。只有事件被标记为已解决（有了结束时间）或被删除时，告警才会恢复。
  </Accordion>

  <Accordion title="为什么事件告警都是 Warning？">
    Statuspal 的 Webhook 不推送事件类型和严重程度。如需按服务调整等级，可以在集成的[告警处理](/zh/on-call/integration/alert-integration/alert-pipelines)中按标签 `service_ids` 或告警标题改写等级。
  </Accordion>

  <Accordion title="没有开启 Statuspal 监控，还需要勾选 service.monitored_status.updated 吗？">
    可以不勾选。这个事件只在服务开启了 Statuspal 内置监控时推送，勾选也不会产生多余告警。
  </Accordion>
</AccordionGroup>

## 排查问题

***

* **Send test request 显示错误**：确认推送地址完整（包含 `integration_key`），且集成没有被删除
* **Flashduty 返回参数错误**：推送内容缺少 `data.object.id`，或 `monitored_status` 不是 `up`、`down`
* **事件告警没有恢复**：确认事件已在 Statuspal 中标记为已解决，且 Webhook 勾选了 `incident.updated`
* **服务告警没有恢复**：确认 Webhook 勾选了 `service.monitored_status.updated`，且服务监控已恢复为 `up`