标准告警事件

通过标准 HTTP 协议推送自有系统告警事件到 1Duty，实现告警事件自动化降噪处理

概述

1Duty 已经适配了大部分常见监控系统的告警协议（如 Prometheus、Zabbix、Grafana 等），你可以通过告警接入直接对接这些系统。

但如果你使用的是自研的监控系统，或者需要将业务系统中的自定义告警推送到 1Duty，可以使用标准告警事件接口。该接口提供了一个通用的 HTTP 推送协议，支持任意系统向 1Duty 发送告警事件，享受自动化降噪、智能分派、升级通知等完整能力。

获取推送地址

按照以下步骤获取推送地址：

进入集成中心，选择或创建一个集成
进入集成详情页面，切换到 Webhook 配置区域
找到已生成的 Webhook URL
复制该 URL，在你的系统中作为告警推送目标地址使用

每个 Webhook URL 包含唯一的 webhook_key，用于标识告警来源。请妥善保管，避免泄露。

请求描述

使用标准 HTTP POST 请求向 1Duty 推送告警事件。

请求方式

Method	POST
Content-Type	application/json
URL	`https://api.1duty.com/webhook/{webhook_key}`

请求参数

字段	必填	类型	说明
`title`	是	string	告警标题，最大长度 512 个字符。用于展示告警的简要描述。
`event_status`	是	string	告警状态，枚举值： `Critical` -- 严重告警 `Warning` -- 警告告警 `Info` -- 信息告警 `Ok` -- 恢复（自动关闭已有告警）
`alert_key`	否	string	告警唯一标识，最大长度 255 个字符。用于告警去重和自动恢复。相同 `alert_key` 的告警会被聚合为同一条事件，发送 `Ok` 状态时需要携带对应的 `alert_key` 以自动关闭告警。
`description`	否	string	告警详细描述，最大长度 2048 个字符。支持更丰富的告警上下文信息。
`labels`	否	map<string, string>	告警标签，键值对形式。用于携带告警上下文信息，如主机名、服务名、地域等，便于后续分派和筛选。

请求示例

curl -X POST "https://api.1duty.com/webhook/your_webhook_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "服务器 CPU 使用率超过 90%",
    "event_status": "Critical",
    "alert_key": "host-10.0.0.1-cpu-high",
    "description": "生产服务器 10.0.0.1 的 CPU 使用率持续 5 分钟超过 90%，当前值 95.2%",
    "labels": {
      "host": "10.0.0.1",
      "service": "api-gateway",
      "region": "cn-hangzhou",
      "env": "production"
    }
  }'

告警恢复示例：

curl -X POST "https://api.1duty.com/webhook/your_webhook_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "服务器 CPU 使用率恢复正常",
    "event_status": "Ok",
    "alert_key": "host-10.0.0.1-cpu-high",
    "description": "生产服务器 10.0.0.1 的 CPU 使用率已恢复至正常水平，当前值 45.3%"
  }'

响应说明

推送请求的响应格式如下：

成功响应

{
  "code": 0,
  "message": "success"
}

失败响应

{
  "code": 400,
  "message": "invalid request: title is required"
}

常见错误码：

HTTP 状态码	code	说明
200	0	推送成功
400	400	请求参数错误（缺少必填字段或格式不正确）
401	401	webhook_key 无效或已过期
429	429	请求频率超限，请稍后重试
500	500	服务器内部错误

字段映射

推送的告警字段会按以下规则映射为 1Duty 内部的事件字段：

推送字段	1Duty 事件字段	映射说明
`title`	事件标题	直接映射为事件的标题
`event_status`	事件级别 / 状态	Critical/Warning/Info 映射为事件严重级别；Ok 触发事件自动恢复
`alert_key`	事件聚合键	相同 alert_key 的告警聚合为同一事件，实现去重和自动恢复
`description`	事件描述	直接映射为事件的详细描述
`labels`	事件标签	映射为事件的标签（Tags），可用于分派策略条件匹配和告警筛选

最佳实践

设置有意义的 alert_key

建议使用能唯一标识告警来源的组合作为 alert_key，例如 主机-指标-阈值类型 的格式。这样系统可以正确地对同一来源的告警进行去重聚合，避免重复告警产生多条事件。

// 推荐的 alert_key 格式
"alert_key": "host-10.0.0.1-cpu-high"
"alert_key": "service-payment-error-rate"
"alert_key": "db-master-connection-pool-full"

使用 labels 丰富告警上下文

通过 labels 携带丰富的告警上下文信息，便于值班人员快速定位问题。常见的标签包括：

host -- 主机 IP 或主机名
service -- 服务名称
region -- 地域 / 数据中心
env -- 环境（production / staging / dev）
team -- 所属团队

及时发送恢复事件

当告警条件恢复正常时，务必发送 event_status: "Ok" 的事件，并携带对应的 alert_key。这样 1Duty 会自动关闭对应的事件，减少值班人员的手动操作和不必要的通知打扰。

如果不发送恢复事件，告警事件将一直处于打开状态，需要值班人员手动关闭。建议在监控系统中配置自动恢复逻辑。

合理使用告警级别

根据告警的实际影响程度选择合适的 event_status：

Critical -- 影响核心业务、需要立即处理的严重告警（如服务宕机、数据库不可用）
Warning -- 可能导致问题、需要关注的警告告警（如磁盘空间不足、响应延迟升高）
Info -- 仅供通知、不需要立即处理的信息告警（如部署完成、配置变更）

通知渠道

当告警事件通过标准接口推送到 1Duty 后，系统会根据分派策略将告警通知到相关值班人员。1Duty 支持以下通知渠道：

渠道	说明
钉钉	通过钉钉机器人推送告警消息到钉钉群或个人
飞书	通过飞书机器人推送告警消息到飞书群或个人
企业微信	通过企业微信机器人推送告警消息到企业微信群或个人
短信	通过短信通知值班人员，适用于紧急告警场景
电话	通过语音电话通知值班人员，确保严重告警能被立即响应

建议为不同级别的告警配置不同的通知渠道。例如 Critical 告警使用电话+短信+IM 多通道通知，Warning 告警使用 IM 通知即可。具体配置请参考通知设置。

← 分派策略成员管理 →