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

# Formant 告警集成

> 通过 Formant 事件的 Webhook 转发，把机器人和设备事件同步到 Flashduty On-call。

Formant 的事件（Event）触发时，可以通过 **Webhook forwarding** 把事件以 JSON 发送到指定地址。把 Webhook 指向 Flashduty 的推送地址后，每个 Formant 事件会在 Flashduty 中产生一条告警。

Formant 事件只发送一次，没有恢复通知，Flashduty 中的告警不会自动恢复。请按 [告警恢复和自动关闭](#告警恢复和自动关闭) 开启超时自动关闭。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Formant 中配置

***

<Steps>
  <Step title="创建 Webhook">
    1. 登录 Formant，打开左上角菜单，点击 **Settings**
    2. 点击 **Integrations**，向下找到 **Webhooks**，点击 **Connect**
    3. 填写 Webhook 名称，**URL** 填 Flashduty 集成的完整推送地址（以 `https://` 开头，包含 `integration_key`）
    4. 附加参数（parameters）可以留空，Flashduty 不读取它们。保存
  </Step>

  <Step title="为事件开启 Webhook 转发">
    1. 进入 **Settings → Events**，打开一个已有事件，或点击 **Add Event Trigger** 新建事件
    2. 在 **Actions** 页签中找到 **Webhook forwarding**，选择上一步创建的 Webhook
    3. 在 **Notification** 中设置事件的严重程度（Info、Warning、Error、Critical），它决定 Flashduty 告警的等级
    4. 保存。需要转发的每个事件都要单独选择 Webhook
  </Step>

  <Step title="验证">
    让一个已转发的事件触发一次（例如让设备离线，或让数据点超过阈值），确认 Flashduty 出现一条告警，标题为事件消息（例如 `Oven temperature high`）。
  </Step>
</Steps>

## 告警恢复和自动关闭

***

Formant 事件一经触发就不可修改，Webhook 对每个事件只发送一次。请求体中没有表示事件结束或恢复的字段，所以 Flashduty 中的告警不会自动恢复。

每个 Formant 事件对应一条独立的 Flashduty 告警，需要手动关闭，或在接收该集成的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)。建议 2 小时，并按设备问题的处理时效调整。

## Alert Key

***

Alert Key 为 Formant 事件 ID（`payload.id`）。同一个事件重复投递会合并到同一条告警；不同事件（即使来自同一个事件触发器和同一台设备）是不同的告警。请求中缺少事件 ID 时，Flashduty 会生成随机 Alert Key，这条告警同样不会被合并。

## 状态和告警等级

***

告警的状态等于告警等级，不会恢复。

| Formant 严重程度 `severity` | Flashduty 等级 |
| :- | :- |
| `critical` | Critical |
| `error` | Critical |
| `warning` | Warning |
| `info` | Info |
| 缺失或其他值 | Warning |

## 告警内容

***

* **标题**：事件消息 `message`；缺失时为 `Formant event on <数据流名称>`，再缺失时为 `Formant event`
* **描述**：设备 ID、数据流、数据点取值、事件时间和 Formant 中的事件链接

| 标签 | 来源 |
| :- | :- |
| `event_type` | 事件类型 `eventType`，例如 `alert` |
| `event_id` | 事件 ID |
| `severity` | Formant 中的严重程度 |
| `device_id` | 设备 ID |
| `stream_name` / `stream_type` | 数据流名称、类型 |
| `value` | 触发事件的数据点取值；对象类型的取值按 JSON 文本保存 |
| `source_url` | Formant 中的事件链接 |
| 设备标签 | 事件 `tags` 中的每个键值；键中的 `.`、`-` 等字符替换为 `_`，不覆盖上面的标签 |

## 排查问题

***

* **Flashduty 没有收到事件**：确认事件的 **Actions** 中已在 **Webhook forwarding** 选择了该 Webhook；确认 Webhook 的 URL 是完整的推送地址，包含 `integration_key`
* **Flashduty 返回参数错误**：请求体不是 JSON，或缺少 `payload` 对象。请使用 Formant 自带的 Webhook 转发，不要改写请求体
* **告警一直不关闭**：Formant 不发送恢复通知。请在协作空间中开启超时自动关闭，或手动关闭


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