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

# Webhook 自定义操作

> 配置自定义操作，当故障发生特定操作时，系统通过 HTTP 回调您配置的地址

配置故障 自定义操作，允许您在故障排查期间，快速调用外部接口，实现故障自愈、信息丰富等任何自定义操作。

## 创建操作

1. 登录 Flashduty 控制台，进入【集成中心-Webhook】
2. 点击添加 自定义操作 集成
3. 配置 操作名称，此名称将以按钮的形式体现在故障详情中
4. 配置 管理团队（可选），只有该团队成员可以编辑此集成配置
5. 配置 协作空间，可以配置多个，但每个协作空间至多添加五个 自定义操作
6. 配置 Endpoint、自定义 Headers
7. 保存，完成

## 编辑已保存的操作

保存之后，Endpoint 和自定义 Payload 照常显示，可以直接修改。自定义 Headers 的取值按密钥处理，Flashduty 不会再把它们显示回来：详情页和编辑页里，每个 Header 的值都显示为 `******`。

编辑时保存规则如下：

| Header 的值 | 保存结果 |
| - | - |
| 保持 `******` 不动 | 沿用已保存的值，不会被覆盖成掩码 |
| 填入新值 | 新值覆盖已保存的值 |

想更换某个 Header 的取值，需要重新输入一遍。如果改了 Endpoint，仍是 `******` 的 Header 需要重新填写，否则已保存的值会被发送到新的地址；编辑页会在这些 Header 下方提示。

## 推送描述

### 请求方式

POST, Content-Type:"application/json"

### 请求 Payload

| 字段 | 类型 | 必含 | 释义 |
| :-: | :-: | :-: | :- |
| event\_time | int64 | 是 | 事件发生 `毫秒时间戳` |
| event\_type | string | 是 | 事件类型，固定值 `i_custom` |
| event\_id | string | 是 | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` |
| event\_detail | object | 否 | 事件明细，固定结构见下方[事件明细](#EventDetail) |
| person | [Person](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#Person) | 否 | 操作人，仅人为动作时存在 |
| incident | [Incident](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#Incident) | 是 | 故障详情 |

`person`、`incident`（含 [Responder](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#Responder)、[AssignedTo](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#AssignedTo)、[Image](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#Image)）的字段与[故障 Webhook](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#请求-payload)中的相同，差异如下：

* `incident.alerts` 额外返回关联告警列表，字段见下方 [Alert](#Alert)；无关联告警时不返回该字段。
* `incident.links` 不返回，请使用故障 Webhook 获取。

**Alert**:

| 字段 | 类型 | 必含 | 释义 |
| :-: | :-: | :-: | :- |
| alert\_id | string | 是 | 告警 ID |
| account\_id | int64 | 是 | 账户 ID |
| integration\_id | int64 | 是 | 集成 ID |
| channel\_id | int64 | 是 | 协作空间 ID |
| title | string | 是 | 告警标题 |
| title\_rule | string | 否 | 标题生成规则 |
| description | string | 否 | 告警描述 |
| alert\_key | string | 是 | 告警关联依据 |
| alert\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info |
| alert\_status | string | 是 | 告警状态，枚举值：Critical，Warning，Info，Ok |
| progress | string | 是 | 处理进度，枚举值：Triggered，Closed |
| created\_at | int64 | 是 | 创建时间 |
| updated\_at | int64 | 是 | 更新时间 |
| start\_time | int64 | 是 | 首次触发时间（平台接收到的首个事件的时间），Unix 秒时间戳 |
| last\_time | int64 | 是 | 最新事件时间（平台接收到的最新事件时间），Unix 秒时间戳 |
| end\_time | int64 | 否 | 告警恢复时间（平台上一次接收到结束类型事件的时间），Unix 秒时间戳，默认为 0 |
| close\_time | int64 | 否 | 关闭时间，不同于 end\_time，这个是处理进度的关闭，不代表告警真的恢复。Unix 秒时间戳，默认为 0 |
| ever\_muted | bool | 是 | 是否曾被静默策略静默 |
| labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串 |
| event\_cnt | int64 | 否 | 关联事件个数 |
| images | \[][Image](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#Image) | 是 | 告警图片列表，无图片时为 null |

自定义操作中的告警对象有以下限制：

* 不返回 `incident`、`integration_ref_id`、`data_source_type`。
* `integration_name`、`integration_type`、`channel_name`、`channel_status`、`responder_name`、`responder_email`、`data_source_name`、`data_source_ref_id` 恒为空字符串。
* `data_source_id` 同 `integration_id`，请使用 `integration_id`。

**event\_detail**（i\_custom 固定结构）：

| 字段 | 类型 | 必含 | 释义 |
| :- | :-: | :-: | :- |
| integration\_id | int64 | 否 | 触发的自定义操作集成 ID |
| integration\_name | string | 否 | 触发的自定义操作集成名称 |

### 请求响应

HTTP status code 为 200，认为推送成功。

### 请求示例

```
curl -X POST 'https://example.com/incident/action?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
    "event_detail":{
        "integration_id":1234567890123,
        "integration_name":"重启主机"
    },
    "event_id":"fac0599a2a25529ba2362c0c184b6cfb",
    "event_time":1700208013988,
    "event_type":"i_custom",
    "incident":{
        "account_id":74058170041504,
        "account_name":"示例科技",
        "ack_time":0,
        "alert_cnt":1,
        "alerts":[
            {
                "account_id":74058170041504,
                "alert_id":"6551f37f8713372ad1054d54",
                "alert_key":"asdflasdfl2xzasd112621",
                "alert_severity":"Critical",
                "alert_status":"Critical",
                "channel_id":1973372625504,
                "channel_name":"",
                "channel_status":"",
                "close_time":0,
                "created_at":1699869567,
                "data_source_id":2398086111504,
                "data_source_name":"",
                "data_source_ref_id":"",
                "description":"cpu.idle < 20%",
                "end_time":0,
                "event_cnt":1,
                "ever_muted":false,
                "images":null,
                "integration_id":2398086111504,
                "integration_name":"",
                "integration_type":"",
                "labels":{
                    "check":"CPU 使用率过高",
                    "cluster":"nj",
                    "metric":"node_cpu_seconds_total",
                    "resource":"es.nj.01",
                    "service":"engine"
                },
                "last_time":1699869562,
                "progress":"Triggered",
                "responder_email":"",
                "responder_name":"",
                "start_time":1699869562,
                "title":"nj / es.nj.01 - CPU 使用率过高",
                "title_rule":"$cluster::$resource::$check",
                "updated_at":1699869576
            }
        ],
        "assigned_to":{
            "assigned_at":1699869576,
            "escalate_rule_id":"6509344bc1d50d723ca04986",
            "escalate_rule_name":"默认分派",
            "id":"VobpBqvTuXgQ7BZzJ2Qu94",
            "layer_idx":0,
            "type":"assign"
        },
        "channel_id":1973372625504,
        "channel_name":"支付服务",
        "channel_status":"enabled",
        "close_time":0,
        "created_at":1699869576,
        "creator":{
            "email":"alice@example.com",
            "person_id":1552048792504,
            "person_name":"Alice"
        },
        "creator_id":1552048792504,
        "data_source_id":2398086111504,
        "dedup_key":"asdflasdfl2xzasd112621",
        "description":"cpu.idle < 20%",
        "detail_url":"https://console.example.com/incident/detail/6551f3888713372ad1054d57",
        "end_time":0,
        "fields":{
            "impacted_services":[
                "passport",
                "order"
            ],
            "priority":"P3"
        },
        "group_method":"p",
        "has_unfinished_work_item":false,
        "images":null,
        "impact":"",
        "incident_id":"6551f3888713372ad1054d57",
        "incident_severity":"Critical",
        "incident_status":"Critical",
        "integration_id":2398086111504,
        "labels":{
            "check":"CPU 使用率过高",
            "cluster":"nj",
            "metric":"node_cpu_seconds_total",
            "resource":"es.nj.01",
            "service":"engine"
        },
        "last_time":1699869562,
        "num":"054D57",
        "post_mortem_id":"0",
        "progress":"Triggered",
        "resolution":"",
        "responders":[
            {
                "acknowledged_at":0,
                "assigned_at":1699869576,
                "email":"bob@example.com",
                "person_id":1234648032504,
                "person_name":"Bob"
            }
        ],
        "root_cause":"",
        "silence_url":"https://console.example.com/channel/detail/1973372625504?tab=alertSuppression&fromIncidentId=6551f3888713372ad1054d57",
        "snoozed_before":0,
        "start_time":1699869562,
        "title":"nj / es.nj.01 - CPU 使用率过高",
        "updated_at":1699929113
    },
    "person":{
        "email":"bob@example.com",
        "person_id":1999632289504,
        "person_name":"Bob"
    }
}' -v
```

## 自定义请求体与值映射

自定义操作与故障 Webhook 一样支持 **自定义请求体** 和 **值映射**，变量路径引用上方[请求 Payload](#请求-payload)中的字段。语法和示例见[故障 Webhook](https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook.md#自定义请求体)。

## 使用场景

### 重启主机

当主机内存或 CPU 打满，触发主机重启脚本，快速完成主机重启。

### 信息丰富

当故障发生时，回调您的服务，根据告警详情调取 Tracing、Logging、拓扑等信息，主动调用 Flashduty Open API 来更新故障信息，比如增加标签或设定自定义字段，辅助排障。

### 回滚变更

当发生故障时，如果确定故障由变更导致，可以直接触发回调到您的部署平台，开启回滚进程，加速故障恢复。

### 更新 status page

当确定故障影响到线上服务，可以触发外部 status page 更新，及时的通知到您的客户或上下游。

## 常见问题

1. **服务是否有响应超时时间？**

   * 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败

2. **推送失败后是否会持续推送？**

   仅以下网络错误会重试，最多 1 次：

   * 连接超时或读写超时（`i/o timeout`）
   * 连接被对端提前关闭（`EOF`）

   请求已发出、等待响应头超时的，不重试。

3. **推送来源可信 IP 白名单？**

   * `47.94.95.118`、`123.56.8.183`、`47.94.193.81` 和 `1.13.19.96`（SaaS 版本；私有化部署的推送来源为您自有环境的出口地址，请向您的基础设施团队确认）
   * 未来可能会更新，请定期查验


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