> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# 故障 Webhook
> 配置故障 Webhook，当故障发生特定操作时，系统通过 HTTP 回调您配置的地址
配置故障 Webhook，当故障发生特定操作（如触发、关闭）时，系统通过 HTTP 回调您配置的地址。回调内容将包含故障最新关键信息，您可以与自研工具进行集成。
## 一、事件类型
目前支持以下事件类型，未来可能会增加。
| 事件类型 | 释义 |
| :------------: | :------------ |
| i\_new | 创建故障（自动或手动创建） |
| i\_assign | 分派故障（自动或手动分派） |
| i\_a\_rspd | 添加处理人 |
| i\_snooze | 手动暂缓故障 |
| i\_wake | 取消暂缓故障 |
| i\_ack | 手动认领故障 |
| i\_unack | 取消认领故障 |
| i\_storm | 触发风暴提醒 |
| i\_custom | 触发自定义操作 |
| i\_rslv | 关闭故障（自动或手动关闭） |
| i\_reopen | 重新打开故障 |
| i\_merge | 手动合并故障 |
| i\_comm | 添加评论 |
| i\_r\_title | 更新故障标题 |
| i\_r\_desc | 更新故障描述 |
| i\_r\_impact | 更新故障影响 |
| i\_r\_rc | 更新故障根因 |
| i\_r\_rsltn | 更新故障解决办法 |
| i\_r\_severity | 更新故障严重程度 |
| i\_r\_field | 更新故障自定义字段 |
## 二、推送描述
### 请求方式
POST, Content-Type:"application/json"
### 请求 Payload：
| 字段 | 类型 | 必含 | 释义 |
| :---------: | :-------------------: | :-: | :----------------------------------- |
| event\_time | int64 | 是 | 事件发生`毫秒时间戳` |
| event\_type | string | 是 | 事件类型，枚举值见[事件类型](#EventTypes) |
| event\_id | string | 是 | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` |
| person | [Person](#Person) | 否 | 操作人，仅人为动作时存在 |
| incident | [Incident](#Incident) | 是 | 故障详情 |
**Person**:
| 字段 | 类型 | 必含 | 释义 |
| :----------: | :----: | :-: | :---- |
| person\_id | int64 | 是 | 人员 ID |
| person\_name | string | 是 | 人员名称 |
| email | string | 是 | 邮件地址 |
**Responder**:
| 字段 | 类型 | 必含 | 释义 |
| :--------------: | :----: | :-: | :---- |
| person\_id | int64 | 是 | 人员 ID |
| person\_name | string | 是 | 人员名称 |
| email | string | 是 | 邮件地址 |
| assigned\_at | int64 | 否 | 分派时间 |
| acknowledged\_at | int64 | 否 | 认领时间 |
**Incident**:
| 字段 | 类型 | 必含 | 释义 |
| :----------------: | :------------------------: | :-: | :------------------------------------------------------------------------------------ |
| incident\_id | string | 是 | 故障 ID |
| title | string | 是 | 故障标题 |
| description | string | 否 | 故障描述 |
| impact | string | 否 | 故障影响 |
| root\_cause | string | 否 | 故障根本原因 |
| resolution | string | 否 | 故障解决办法 |
| incident\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info |
| incident\_status | string | 是 | 故障状态，枚举值：Critical，Warning，Info，Ok |
| progress | string | 是 | 处理进度，枚举值：Triggered，Processing，Closed |
| created\_at | int64 | 是 | 创建时间 |
| updated\_at | int64 | 是 | 更新时间 |
| start\_time | int64 | 是 | 触发时间，Unix 秒时间戳 |
| last\_time | int64 | 否 | 最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0 |
| end\_time | int64 | 否 | 恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0 |
| ack\_time | int64 | 否 | 首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0 |
| close\_time | int64 | 否 | 关闭时间，end\_time代表故障恢复时间，close\_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0 |
| snoozed\_before | int64 | 否 | 暂缓截止时间 |
| labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息 |
| fields | map\[string]interface{} | 否 | 自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型 |
| creator | [Person](#Person) | 否 | 创建人员信息，仅手动创建故障时存在 |
| closer | [Person](#Person) | 否 | 关闭人员信息，仅手动关闭故障时存在 |
| responders | \[][Responder](#Responder) | 否 | 处理人员信息列表，仅故障被分派后存在。对于i\_new事件，此值可能为空 |
| alert\_cnt | int64 | 否 | 关联告警个数 |
| channel\_id | int64 | 否 | 协作空间ID，为0代表不属于任何空间 |
| channel\_name | string | 否 | 协作空间名称 |
| detail\_url | string | 是 | 详情地址 |
| group\_method | string | 否 | 聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合 |
### 请求响应
HTTP status code 为 200，认为推送成功。
### 请求示例
```
curl -X POST 'https://example.com/incident/webhook?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
"event_id":"fac0599a2a25529ba2362c0c184b6cfb",
"event_time":1689335086948,
"event_type":"i_new",
"incident":{
"account_id":74058170041504,
"account_name":"头铁科技kk",
"ack_time":0,
"alert_cnt":0,
"assigned_to":{
"assigned_at":1689335086,
"escalate_rule_id":"64abb8a687e7984845822139",
"escalate_rule_name":"默认分派",
"id":"NBRbNwDSTSMijKXdLtBU3T",
"layer_idx":0,
"type":"assign"
},
"channel_id":1840312623504,
"channel_name":"Reduce Noise",
"close_time":0,
"created_at":1689335086,
"creator":{
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"头铁"
},
"creator_id":1552048792504,
"data_source_id":0,
"dedup_key":"",
"description":"",
"detail_url":"http://10.206.0.17:8567/incident/detail/64b1352e376e32c85c56e25b",
"end_time":0,
"equals_md5":"",
"group_method":"n",
"impact":"",
"incident_id":"64b1352e376e32c85c56e25b",
"incident_severity":"Critical",
"incident_status":"Critical",
"labels":{
"check": "cpu idle low"
},
"last_time":1689335086,
"num":"56E25B",
"progress":"Triggered",
"resolution":"",
"responder_ids":[
1552048792504
],
"responders":[
{
"acknowledged_at":0,
"assigned_at":1689335086,
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"头铁"
}
],
"root_cause":"",
"snoozed_before":0,
"start_time":1689335086,
"title":"ysy028",
"updated_at":1689335086
},
"person":{
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"头铁"
}
}' -v
```
## 三、配置指南
进入 **集成中心** → **Webhook** → 添加或编辑 **故障 Webhook** 集成。
### 基础设置
填写集成名称和描述，便于后续管理。
### Webhook 设置
| 配置项 | 说明 |
| :----------- | :---------------------------------------------------- |
| **Endpoint** | 接收回调的 HTTP/HTTPS 地址，必须以 `http://` 或 `https://` 开头 |
| **TLS 验证** | 默认启用。关闭后将跳过目标服务器的 TLS 证书验证，适用于测试环境或自签名证书场景 |
| **Headers** | 自定义请求头，以 Key-Value 形式添加，支持添加多个 |
| **协作空间** | 选择 **全部空间** 或 **部分空间**。选择部分空间时，仅该空间下的故障事件会触发回调 |
| **事件类型** | 勾选需要订阅的事件类型（参见[事件类型](#EventTypes)），支持全选。仅选中的事件类型会触发回调 |
关闭 TLS 证书验证可能存在中间人攻击风险，建议仅在测试环境或使用自签名证书时关闭。
### 自定义请求体
默认情况下，系统会按照上述 [Payload 结构](#请求-payload)推送完整的 JSON 数据。如果你的接收方对数据格式有特殊要求，可以通过**自定义请求体**来重新组织推送内容。
使用 `{{字段路径}}` 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。
**变量语法：**
* 用 `.` 分隔路径层级，如 `{{incident.title}}` 引用故障标题
* 支持数组索引访问，如 `{{incident.responders.0.email}}` 引用第一个处理人的邮箱
* 当整个值只有一个变量时（如 `"{{incident.labels}}"`），会保留原始数据类型（对象、数组、数字等）
* 当变量与其他文本混合时（如 `"故障：{{incident.title}}"`），变量会被转为字符串拼接
**示例：**
将默认 Payload 转为自定义格式推送到企业内部系统：
```json theme={null}
{
"msg_type": "incident",
"event": "{{event_type}}",
"content": {
"id": "{{incident.incident_id}}",
"name": "{{incident.title}}",
"severity": "{{incident.incident_severity}}",
"status": "{{incident.progress}}",
"channel": "{{incident.channel_name}}",
"url": "{{incident.detail_url}}",
"labels": "{{incident.labels}}",
"responders": "{{incident.responders}}"
}
}
```
如果变量路径在默认 Payload 中不存在，系统会保留原始的 `{{...}}` 文本不做替换。建议先通过调用历史查看实际推送的默认 Payload，确认可用的字段路径。
## 四、调用历史
故障 Webhook 提供完整的调用历史记录，方便你排查推送是否成功以及调试回调接口。
### 查看调用历史
进入故障 Webhook 集成详情页，切换到 **调用历史** 页签即可查看。
### 筛选与搜索
| 筛选项 | 说明 |
| :-------- | :----------------------------------------------- |
| **时间范围** | 支持选择最近 1 小时、6 小时、1 天、7 天，或自定义时间范围（最多查看最近 7 天的数据） |
| **故障 ID** | 输入故障 ID 进行精确搜索 |
| **事件类型** | 按事件类型筛选记录 |
| **请求状态** | 按成功或失败筛选 |
### 历史记录字段
| 字段 | 说明 |
| :-------- | :--------------------------- |
| **触发时间** | 事件触发的时间 |
| **事件类型** | 触发的事件类型（如 `i_new`、`i_ack` 等） |
| **故障 ID** | 关联的故障 ID，可点击跳转到故障详情 |
| **事件 ID** | 本次回调的唯一标识，可用于去重 |
| **请求状态** | 成功或失败，附带 HTTP 状态码 |
| **耗时** | 请求往返耗时 |
| **请求次数** | 包括首次请求和重试次数 |
### 查看调用详情
点击某条记录的 **查看详情**，可查看完整的请求和响应信息：
* **Request**：包括 Endpoint、Request Headers 和 Request Payload
* **Response**：成功时显示 Response Headers 和 Response Body；失败时显示 Error Message
## 五、常见问题
1. **服务是否有响应超时时间？**
* 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败
2. **推送失败后是否会持续推送？**
针对特定的网络错误，会进行重试，最多重试1次:
* context deadline exceeded (排除 awaiting headers)
* i/o timeout
* eof
3. **如何保证推送顺序？**
* 理论上同一个故障的事件是按照时间顺序进行推送，但是重试等情况可能会导致乱序
* 服务可以根据 event\_time 进行过滤，如果已经收到了更晚的事件，可以直接过滤掉更早的事件，每一次推送都会携带最新的、完整的信息，偶尔丢失事件是可以容忍的
4. **推送来源可信 IP 白名单？**
* {ip_whitelist}
* 未来可能会更新，请定期查验