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

# Cato Networks 告警集成

> 通过 Cato 管理控制台（CMA）的自定义 Body Webhook，将站点运维事件（Site Operations story）和其他告警同步到 Flashduty On-call。

Cato Networks 的 Webhook 没有固定的请求体，Body 由用户在 CMA 中自行编写。本页提供一份请求体模板，Flashduty 按该模板解析。以 `storyId`（站点运维事件 ID）作为同一事件的标识：事件打开或更新时触发或更新告警，`storyStatus` 变为 `RESOLVED`（或 `endDate` 有值）时告警恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Cato 中配置

***

需要具备在 CMA 中管理订阅（Subscriptions）的权限。

<Steps>
  <Step title="新建 Webhook">
    1. 进入 CMA，选择 **Account > Subscriptions**，打开 **Webhooks** 页签，点击 **New Webhook**
    2. 填写名称并启用
    3. 请求方式选择 **POST**（Create），URL 粘贴 Flashduty 的完整推送地址，地址中需包含 `integration_key`
    4. 认证方式选择无需认证即可，`integration_key` 已在地址中
  </Step>

  <Step title="粘贴请求体模板">
    Body 选择 **Custom**，粘贴以下模板。`${字段:}` 会被 Cato 替换为对应字段的值，冒号后为字段无值时的默认值（此处为空）：

    ```json theme={null}
    {
      "storyId": "${storyId:}",
      "correlationId": "${correlationId:}",
      "storyStatus": "${storyStatus:}",
      "alertType": "${alertType:}",
      "level": "${level:}",
      "title": "${title:}",
      "subject": "${subject:}",
      "accountName": "${accountName:}",
      "siteName": "${siteName:}",
      "ISPName": "${ISPName:}",
      "startDate": "${startDate:}",
      "endDate": "${endDate:}"
    }
    ```

    字段含义见 [Understanding the JSON Fields for Alert Integrations](https://knowledge.catonetworks.com/docs/understanding-the-json-fields-for-alert-integrations)。不要删除 `storyId`、`correlationId`、`storyStatus` 和 `endDate`，它们决定告警的归并与恢复。
  </Step>

  <Step title="选择订阅并验证">
    1. 在 **Account > Subscriptions** 中，将该 Webhook 作为需要接收的告警类型（站点运维事件等）的订阅投递目标
    2. 点击 Webhook 页面的 **Test**，Cato 文档没有给出测试请求的内容，Flashduty 按普通告警处理；若测试请求不含 `storyId` 与 `correlationId` 会返回参数错误，若含有则产生一条独立告警，请在验证后手动关闭
    3. 触发真实事件（如断开测试站点的 Socket），确认 Flashduty 收到活动告警；事件解决后确认该告警恢复
  </Step>
</Steps>

<Warning>
  `storyId` 只存在于站点运维事件，其他类型的告警没有此字段，此时 Flashduty 改用 `correlationId` 作为 Alert Key。这类告警只有在 `endDate` 有值时才会恢复，否则请在接收告警的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议 24 小时。Cato 的关联更新（同一 story 的后续更新）依赖其 XOps 关联能力，未开通时每次通知可能是独立事件。
</Warning>

## Alert Key

***

Flashduty 使用 `storyId` 作为 Alert Key，`storyId` 为空时使用 `correlationId`。Cato 文档对两者的定义：`storyId` 是 "Unique identifier for the Site Operations story"，`correlationId` 是 "Unique identifier used to correlate related events, messages, or operations"。标题、等级、时间的变化不会改变 Alert Key。两者都缺失的请求会被拒绝并提示字段名。

## 状态和告警等级

***

`storyStatus` 为 `RESOLVED`，或 `endDate` 不为空时，告警恢复；`OPEN`、`IN_PROGRESS` 等其他状态为触发或更新。告警等级由 `level` 决定：

| Cato `level` | Flashduty 等级 |
| :- | :- |
| `CRITICAL` | Critical |
| `HIGH` | Warning |
| `MEDIUM` | Warning |
| `LOW` | Info |
| 空值或其他值 | Warning |

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `story_id` | `storyId` |
| `correlation_id` | `correlationId` |
| `story_status` | `storyStatus` |
| `alert_type` | `alertType` |
| `level` | `level` |
| `check` | 标题 |
| `account_name` | `accountName` |
| `site` | `siteName` |
| `isp` | `ISPName` |

## 排查问题

***

* **Cato 测试失败**：确认 URL 完整且包含 `integration_key`，请求方式为 POST
* **Flashduty 返回参数错误**：确认 Body 是合法 JSON，且包含 `storyId` 或 `correlationId`。如果标题或摘要中含有双引号，Cato 替换后可能破坏 JSON，可从模板中去掉 `title` 或 `subject` 字段
* **告警没有恢复**：确认模板中保留了 `storyStatus` 和 `endDate`，并且恢复通知也投递到了该 Webhook