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

# Instatus 告警集成

> 通过 Webhook 订阅 Instatus 状态页，把事件（Incident）和组件故障同步到 Flashduty On-call。

通过 Instatus 状态页的 Webhook 订阅者，把状态页的变化同步到 Flashduty On-call。状态页发布事件（Incident）或组件（Component）进入故障状态时触发一条 Flashduty 告警，事件变为 `RESOLVED` 或组件恢复为 `OPERATIONAL` 时这条告警自动恢复。计划维护不会生成告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Instatus 中添加 Webhook 订阅者

***

<Steps>
  <Step title="打开 Webhook 订阅者列表">
    登录 [Instatus](https://instatus.com/login)，选择要接入的状态页，进入 **Subscribers**（订阅者），切换到 **Webhook** 标签页。
  </Step>

  <Step title="添加订阅者">
    1. 点击 **Add webhook subscriber**
    2. **Webhook URL**：粘贴 Flashduty 集成的完整推送地址（包含 `integration_key`）
    3. **Email address**：填写一个团队邮箱。推送地址出错时，Instatus 会发邮件到这个地址
    4. 保存。之后可以点击这个订阅者为它命名

    请保持 Instatus 默认的推送格式，不要为这个订阅者自定义请求体：Flashduty 按默认格式解析。表单中的 Webhook Secret 用于签名请求头 `x-instatus-webhook-signature`，Flashduty 不校验签名，保持默认即可；推送地址中的 `integration_key` 用于识别集成，请不要公开。

    同一个集成可以接入多个状态页。不同状态页的告警由页面 ID 区分，不会互相合并或关闭。
  </Step>

  <Step title="验证">
    保存订阅者时，Instatus 会立即发送一次校验推送（Webhook URL 输入框旁的 **RUN** 按钮可以重新触发）。Flashduty 会识别这次校验推送并返回成功、不生成告警。

    也可以驱动一次真实的事件来验证：

    1. 在 Instatus 中进入 **Incidents**，点击 **Add incident**，状态选 **Investigating**，勾选一个受影响的组件并把它的状态设为 **Major outage**，保存并通知订阅者。Flashduty 中出现一条事件告警和一条组件告警，等级都是 Critical
    2. 为这个事件添加一条更新，状态选 **Resolved**，组件恢复为 **Operational**，并通知订阅者。两条告警随之恢复

    发布事件或更新时如果没有通知订阅者，Instatus 不会推送，Flashduty 也不会收到。
  </Step>
</Steps>

## 推送内容

***

Instatus 在事件新增或更新、组件状态变化、计划维护新增或更新时各推送一次 JSON。Flashduty 处理前两类：

**事件新增或更新**

| 字段 | 说明 | 在 Flashduty 中的用途 |
| :- | :- | :- |
| `page.id` | 状态页 ID | Alert Key，标签 `page_id` |
| `page.url` | 状态页地址 | 标签 `page_url` |
| `page.status_description` | 状态页整体状态描述 | 标签 `page_status` |
| `incident.id` | 事件 ID | Alert Key，标签 `incident_id` |
| `incident.name` | 事件名称 | 告警标题 |
| `incident.status` | 事件状态 | 告警状态，标签 `incident_status` |
| `incident.impact` | 事件影响程度 | 标签 `impact`，仅作参考：通过 Instatus 控制台创建的事件，这个字段的取值和 `status` 相同（如 `Investigating`），并不是故障等级 |
| `incident.affected_components[].status` | 受影响组件的状态 | 告警等级，取受影响组件中最高的等级；没有受影响组件时才退回使用 `impact` |
| `incident.url` | 事件详情链接 | 标签 `incident_url` |
| `incident.incident_updates` | 事件的更新记录 | 最新一条更新的正文作为告警描述，超过 8 KB 时截断 |

**组件状态变化**

| 字段 | 说明 | 在 Flashduty 中的用途 |
| :- | :- | :- |
| `page.id` | 状态页 ID | Alert Key，标签 `page_id` |
| `component.id`（或 `component_update.component_id`） | 组件 ID | Alert Key，标签 `component_id` |
| `component.name` | 组件名称 | 告警标题，标签 `component` |
| `component_update.new_status` | 组件的新状态 | 告警等级和状态，标签 `component_status` |

组件告警的标题形如 `Website: major outage`。每条告警还带有标签 `source=instatus`，以及 `page_url`、`page_status`。推送中的退订链接（`meta.unsubscribe`）含有订阅凭据，Flashduty 不会把它写入告警。

## Alert Key

***

Flashduty 按推送类型分别生成 Alert Key：

* 事件：状态页 ID + 事件 ID。同一事件从 `INVESTIGATING` 到 `RESOLVED` 的每次更新落在同一条告警上
* 组件：状态页 ID + 组件 ID。同一组件从故障到恢复的每次状态变化落在同一条告警上

事件和组件的告警互不影响：一次故障通常同时产生事件告警和组件告警，可以用协作空间的[告警聚合](/zh/on-call/channel/noise-reduction)把它们合并到同一个故障。

修改事件名称、组件名称或影响程度不会改变 Alert Key。等级升高时（例如组件从 `PARTIALOUTAGE` 变为 `MAJOROUTAGE`），Flashduty 会新建一条更高等级的告警，原告警保持触发；恢复推送会同时关闭这两条告警。上一条告警恢复后，同一组件再次故障会生成一条新告警。

## 状态和告警等级

***

**组件状态**

| Instatus 组件状态 | Flashduty 状态或等级 |
| :- | :- |
| `MAJOROUTAGE` | Critical |
| `PARTIALOUTAGE` | Warning |
| `DEGRADEDPERFORMANCE` | Info |
| `OPERATIONAL` | 恢复 |
| `UNDERMAINTENANCE` | 忽略，不生成告警 |
| 空值或其他值 | Warning |

**事件**

事件的告警等级取自受影响组件中最高的等级（`affected_components[].status`，取值和组件状态相同，只是大小写和间距不同，如 `Major outage`），告警状态取自事件状态（`status`）：

| Instatus `affected_components[].status` | Flashduty 告警等级 |
| :- | :- |
| `Major outage` | Critical |
| `Partial outage` | Warning |
| `Degraded performance`、`Operational` | Info |
| 空值或其他值 | Warning |

事件没有受影响组件时，退回使用 `impact` 按同样的映射表取等级；但通过控制台创建的事件，`impact` 通常只是 `status` 的文字（例如 `Investigating`），映射不到任何已知取值，等级会落到 Warning。

| Instatus `status` | Flashduty 状态 |
| :- | :- |
| `INVESTIGATING`、`IDENTIFIED`、`MONITORING` | 触发或更新告警 |
| `RESOLVED` | 恢复 |

计划维护（`maintenance` 推送，状态为 `NOTSTARTEDYET`、`INPROGRESS`、`COMPLETED`）属于计划内变更，Flashduty 返回成功但不生成告警。

## 常见问题

***

<AccordionGroup>
  <Accordion title="事件处于 MONITORING 状态时告警会恢复吗？">
    不会。`MONITORING` 表示修复已上线、仍在观察，告警保持触发，直到事件被标为 `RESOLVED`。
  </Accordion>

  <Accordion title="组件从故障直接进入维护，告警为什么没有恢复？">
    `UNDERMAINTENANCE` 会被忽略，不作为恢复信号。组件维护结束、恢复为 `OPERATIONAL` 时，告警才会恢复；也可以在 Flashduty 中手动关闭。
  </Accordion>

  <Accordion title="Flashduty 会校验 Instatus 的签名吗？">
    不会。Flashduty 通过推送地址中的 `integration_key` 识别集成，不读取 `x-instatus-webhook-signature` 请求头。请妥善保管推送地址；泄露后可以删除集成重新创建。
  </Accordion>

  <Accordion title="如何停止接收推送？">
    在 Instatus 的 **Subscribers → Webhook** 中打开这个订阅者，点击 **Unsubscribe**；或删除对应的 Flashduty 集成。
  </Accordion>
</AccordionGroup>

## 排查问题

***

* **Flashduty 中没有告警**：确认发布事件或更新时通知了订阅者；计划维护和 `UNDERMAINTENANCE` 状态本来就不会生成告警
* **Flashduty 返回参数错误**：确认推送地址完整（包含 `integration_key`），且订阅者使用默认推送格式；推送内容缺少 `page.id`、事件 ID 或组件 ID 时会被拒绝
* **Instatus 发邮件提示推送失败**：确认集成没有被删除、推送地址没有被修改
* **同一组件的告警没有恢复**：确认组件已恢复为 `OPERATIONAL`；维护状态不会关闭告警