PagerDuty 集成与接入指南

PagerDuty SaaS 平台的集成与接入总览：账号与基础对象（service/incident/集成/用户）概念、Events API v2 事件接入（routing key）、REST API Key 管理，含官方端点实测响应

PagerDutyPagerDuty告警2026/10/09

PagerDuty 集成与接入指南

目标：梳理 PagerDuty（SaaS 云平台，无自有服务可自托管）的集成接入体系——核心对象概念、Events API v2 事件接入、REST API v2 与 API Key 管理，并给出官方端点的实测响应。涉及真实账号的步骤标注 ⚠️ 前置。

一、环境信息

信息项值
PagerDuty 形态SaaS 云平台（无需安装/部署，官方域名 api.pagerduty.com / events.pagerduty.com）
Events APIv2（https://events.pagerduty.com/v2/enqueue）
REST APIv2（https://api.pagerduty.com）
实测方式官方端点 curl 契约验证 + 本地模拟接收端复现（无真实账号部分标注 ⚠️ 前置）

二、PagerDuty 是什么

PagerDuty 是托管式事件响应（Incident Response）SaaS：接收监控系统（Prometheus/Grafana/Zabbix/自有脚本）推送的告警事件，按既定策略（调度表、升级路径、值守轮转）触达值守人员，并提供事件跟踪、复盘与审计。

  • 无自有服务可部署：所有能力在云上，客户端仅通过 Events API（推事件） 与 REST API（管理） 交互。
  • 事件流：监控告警 → Events API v2（带 routing key）→ 触发/解析 Incident → 调度通知 → 值守确认/关闭。

三、核心对象概念

对象说明与监控侧对应
Service（服务）被监控的逻辑单元（如"线上支付"），事件都归属到 Service对应一组监控目标/一个业务域
Integration（集成）Service 下的一种事件接入方式，Events API v2 集成提供一个 32 位 routing key对应 webhook/推送目标地址
Incident（事件/事故）由 trigger 事件创建、resolve 事件关闭；可包含 assignee、urgency、escalation对应"活动中的告警"
User / Team（用户/团队）值守人员与组织分组对应值班人员名单
Escalation Policy（升级策略）无人响应时按层级/时间升级通知对应告警升级规则
Schedule（调度表）值守轮转排班对应值班表

四、注册与基础准备（⚠️ 前置：需要真实 PagerDuty 账号）

⚠️ 以下步骤需在 PagerDuty 官方控制台完成，本环境无真实账号，步骤按官方流程给出，最终落点在获取两类凭据：routing key（推事件） 与 REST API Token（管资源）。

  1. 访问 https://www.pagerduty.com/ 注册账号并完成邮箱验证、组织（Account）创建。
  2. 左侧 People → Users：添加值守用户，记录其邮箱（REST API 管理用户时用）。
  3. Teams：创建团队（如 ops-team）并归入用户。
  4. Incidents → Escalation Policies：创建升级策略（如 L1 立即通知、15 分钟未响应升 L2）。
  5. Services → New Service：创建 Service（如 production-web），Integration 类型选择 Events API v2，保存后获得 Integration Key（routing key），形如 32 位十六进制字符串。

💡 说明：本指南后续所有演示使用假 routing key（11111111111111111111111111111111），真实接入时替换为控制台获取的值；事件推送的目标 URL 固定为 https://events.pagerduty.com/v2/enqueue。

五、Events API v2：事件接入（推）

5.1 端点与请求格式

POST https://events.pagerduty.com/v2/enqueue
Content-Type: application/json

{
  "routing_key": "11111111111111111111111111111111",
  "event_action": "trigger",
  "dedup_key": "disk-full-db-01",
  "payload": {
    "summary": "磁盘使用率 90%",
    "source": "db-01",
    "severity": "critical",
    "timestamp": "2026-10-08T21:00:00.000Z",
    "custom_details": {"instance": "db-01", "mount": "/data"}
  },
  "client": "ops-script",
  "client_url": "https://ops.example.com"
}
字段必填说明
routing_key是Events API v2 集成的密钥
event_action是trigger（触发）/ acknowledge（确认）/ resolve（解决）
dedup_key否去重键，同键 trigger/resolve 关联为同一 incident
payload.summary是事件摘要（≤1024 字符）
payload.severity是critical/error/warning/info
payload.source是事件来源标识

5.2 curl 实测（真实官方端点）

curl -s -X POST "https://events.pagerduty.com/v2/enqueue" \
  -H "Content-Type: application/json" \
  -d '{"routing_key":"fake","event_action":"trigger","payload":{"summary":"test","source":"test","severity":"info"}}'

实测回显（无效 key 的官方契约响应）：

Invalid routing key

💡 说明：返回 Invalid routing key 证明端点与协议正确，仅凭据无效；合法 key 会返回 {"status":"success","dedup_key":"...","message":"Event processed"}（含 HTTP 202）。可用本地 webhook 模拟端点复现完整请求体（见下节）。

5.3 本地可复现演示（不依赖真实账号）

在服务器起一个回显端点，把 Alertmanager 的 PagerDuty receiver 指向它，即可看到 PagerDuty 将收到的完整事件体。实测（Alertmanager 0.34.1 触发事件）：

{
  "routing_key": "${PD_ROUTING_KEY}",
  "dedup_key": "3821961fee9ba99325d36ab961f8d3d09611051672e0d48ae0196730938bfd49",
  "event_action": "trigger",
  "payload": {
    "summary": "[FIRING:1] DatabaseDown (pg-01 critical)",
    "source": "Alertmanager",
    "severity": "critical",
    "custom_details": {"firing": [...], "num_firing": 1, "num_resolved": 0, "resolved": []}
  },
  "client": "Alertmanager",
  "client_url": "http://alertmanager-srv:9095/#/alerts?receiver=pd"
}

💡 说明：dedup_key 由 Alertmanager 按告警指纹生成，同告警恢复（resolve）时复用同一 key，PagerDuty 据此关联触发/解决。

六、REST API v2：平台管理（管）

  • 基址 https://api.pagerduty.com，鉴权头 Authorization: Token token=<API_TOKEN>，媒体类型 Accept: application/vnd.pagerduty+json;version=2。
  • 典型资源：/users、/teams、/services、/incidents、/escalation_policies、/schedules。

实测契约（无效 Token）：

curl -s -o /dev/null -w "HTTP %{http_code}\n" "https://api.pagerduty.com/users" \
  -H "Authorization: Token token=fake_token" \
  -H "Accept: application/vnd.pagerduty+json;version=2"

实测回显：

HTTP 401

💡 说明：401 即端点可达、鉴权失败；携带合法 Token 时返回 200 与资源列表（详见《PagerDuty REST API 与运维指南》）。

七、API Key 管理

凭据类型用途获取位置权限范围
Events API v2 routing key推送事件（trigger/resolve）Service → Integrations → Events API v2仅该 Service 事件
REST API Token管理用户/服务/事件/策略右上角 用户头像 → User Settings → API Access Keys账号级（可限只读）
OAuth 客户端第三方应用授权Developer Mode → OAuth按 scopes

⚠️ 注意：routing key 与 Token 属系统级密钥，正文一律以 ${VAR} 占位/假值演示，生产通过环境变量或密钥管理注入，取值方法与注入写法如下：

# routing key：控制台 Service → Integrations → Events API v2 复制 32 位值
export PD_ROUTING_KEY=$(cat /etc/pd/routing_key)
# REST API Token：User Settings → API Access Keys 生成
export PD_API_TOKEN=$(cat /etc/pd/token)

泄漏后应立即在控制台轮换对应密钥。

八、常见问题

Q1：推送返回 Invalid routing key？

key 错误或集成类型不是 Events API v2（旧 v1 集成用 service_key 且 URL 不同）。核对 Service 的 Integration 类型与 key。

Q2：事件已返回 success 但没收到通知？

确认 Service 已配置 Escalation Policy，且 policy 内用户有可用联系方式（邮箱/电话/App）并处于 On-Call。

Q3：trigger/resolve 未关联为同一 incident？

两事件必须用相同 dedup_key（或相同 payload 指纹）；Alertmanager 会自动按告警指纹生成一致 key。

Q4：需要把事件转发到本地做联调？

把监控端 webhook 指向本地回显端点即可复现请求体（本指南 五、5.3），无需真实账号即可验证格式。

九、参考链接

PagerDuty 集成与接入指南 - Quzuo