pagerduty-api

PagerDuty API

PagerDuty API는 PagerDuty 계정의 설정을 바꾸거나, 모니터링 도구에서 발생한 이벤트를 PagerDuty로 보내거나, PagerDuty 안에서 일어난 액션을 다른 시스템에 알려주는 등 여러 가지 방식으로 PagerDuty를 프로그래밍 방식으로 다룰 수 있게 해 주는 통합 문서예요. 크게 설정·데이터를 다루는 REST API, 모니터링 이벤트를 비동기로 보내는 Events API(v1/v2), 그리고 PagerDuty 안의 액션을 구독해서 알려주는 Webhook으로 나눌 수 있어요. 이 문서는 핵심 기능(인증/토큰, 이벤트·인시던트·온콜 API, webhook)과 사용 예시를 정리한 거예요.

출처: 문서

본문

REST API (인증/토큰, 인시던트·온콜)

REST API는 PagerDuty 계정에 존재하는 모든 엔티티의 데이터에 접근하고 조작하는 데 사용해요. RESTful 원칙을 따르며 대부분의 엔티티에 대해 create, read, update, delete 표준 CRUD 액션을 제공하죠. REST API로 할 수 있는 일은 다음과 같아요.

• 사용자 추가·설정 (PagerDuty가 사용자에게 알리는 방식 포함)
• 인시던트 대응 workflow 설정
• 누가 온콜(on-call)인지, 언제 알림을 받는지 조회
• 팀의 열린/최근 인시던트 목록 표시
• 모니터링 도구 없이 인시던트 수동 생성

REST API는 모든 요청이 동일한 호스트로 전송돼요.

api.pagerduty.com

제공하는 인증 정보에 따라 해당 계정의 데이터를 받게 되며, JSON만 지원해요 (다른 콘텐츠 타입은 지원하지 않아서 예측 불가능한 결과가 나올 수 있어요). 요청 본문은 JSON으로 보내고 응답도 JSON으로 옵니다.

HTTP 요청 시 적용해야 하는 헤더는 다음과 같아요.

• Accept: API 토큰 버전과 다른 API 버전을 지정할 때 사용 (Versioning 참고)
• Authorization: 모든 요청에 필수 (Authentication 참고)
• Content-Type: POST·PUT 요청 시 필수. MIME 타입은 application/json
• From: 액션을 수행한 사용자로 기록할 이메일. 사용자 생성이나 REST API 인시던트 생성 시 사용

REST API에 접속하려면 TLS(Transport Layer Security)가 필요해요. TLS 1.2와 1.3을 지원하며(보안·성능이 좋은 1.3 권장), 서버 인증서는 DigiCert가 발급·서명하기 때문에 로컬 trust store에 DigiCert 루트 인증서가 포함된 최신 인증서 번들이 필요해요.

인증(Authentication) 상세: 모든 REST API 요청에는 Authorization 헤더가 필수로 들어가요. API 토큰(API access key) 또는 OAuth 토큰을 통해 인증하며, 헤더 값을 통해 해당 계정을 식별해요.

Events API (이벤트)

Events API는 v1과 v2가 있으며, 각종 모니터링 도구를 통해 시스템을 PagerDuty에 연결하는 비동기 API예요. 이벤트는 계정에서 관리하는 서비스에서 발생한 "상황(occurrence)"을 나타내며 PagerDuty에 보내져 처리돼요. 모니터링 도구로부터 얻은 데이터를 actionable한 인시던트로 바꾸는 Event Management 기능을 쓰려면 Events API가 관문이에요.

새 커스텀 통합을 만들 때는 Events API v2 사용을 강력히 권장해요. v2는 PagerDuty 알림에 PD-CEF 필드를 직접 지정할 수 있어서 알림 데이터를 더 풍부하게 만들어 분류·필터링·운영 인텔리전스에 유리하죠.

Events API v2는 alert(문제)와 change(문제가 아닌 시스템 변경) 두 가지 이벤트 타입을 받아요.

이벤트가 PagerDuty에서 어떻게 쓰이는지 보면, alert 이벤트는 서비스에 인시던트를 만들고 온콜 담당자에게 할당돼요. 그러면 담당자의 알림 설정(전화, SMS, 이메일, 모바일 푸시)에 따라 알림이 가죠. 이미 존재하는 문제의 alert가 있으면 하나의 인시던트로 그룹화할 수도 있어요 (Alert De-Duplication).

시작하려면 다음 단계를 따르면 돼요.

1. 아무 PagerDuty 서비스에 통합(integration)을 만든다.
2. Integration Type으로 Events API v2를 선택한다.
3. 새 통합의 integration key를 이벤트 페이로드의 routing_key로 넣는다.
4. alert 또는 change 이벤트 페이로드를 적절한 endpoint로 보낸다.

서비스 통합 키는 어떤 타입의 이벤트든 보낼 수 있어요. 다만 change 이벤트는 규칙셋(ruleset) 통합 키에는 보낼 수 없어요 (규칙셋 키는 R 문자로 시작해요).

응답 코드와 재시도 로직은 다음과 같아요.

Alert 이벤트 보내기 (send-alert-event)

Endpoint는 다음과 같아요.

https://events.pagerduty.com/v2/enqueue

주요 파라미터는 다음과 같아요.

Alert De-Duplication: 모든 alert 이벤트에는 alert를 식별하는 dedup_key가 있어요. 처음 trigger 이벤트를 보낼 때 지정할 수 있고, 생략하면 PagerDuty가 자동으로 생성해서 응답에 돌려줘요. 이후 동일한 dedup_key로 보내는 이벤트는 해당 키에 매칭되는 열려 있는 alert에 적용돼요. alert가 resolve되면 같은 키로 보낸 이후 이벤트는 새 alert를 만들거나(trigger) 버려져요(acknowledge/resolve). alert는 event_action이 trigger인 이벤트에 대해서만 생성돼요.

event_action 동작은 다음과 같아요.

예시 요청 페이로드 (Trigger):

/*
  This example shows how to send a trigger event without a dedup_key.
  In this case, PagerDuty will automatically assign a random and unique key
  and return it in the response object.
  You should store this key in case you want to send an acknowledge or resolve
  event to this incident in the future.
*/
{
  "payload": {
    "summary": "Example alert on host1.example.com",
    "timestamp": "2015-07-17T08:42:58.315+0000",
    "source": "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-prod-003",
    "severity": "info",
    "component": "postgres",
    "group": "prod-datapipe",
    "class": "deploy",
    "custom_details": {
      "ping time": "1500ms",
      "load avg": 0.75
    }
  },
  "routing_key": "samplekeyhere",
  "dedup_key": "samplekeyhere",
  "images": [
    {
      "src": "https://www.pagerduty.com/wp-content/uploads/2016/05/pagerduty-logo-green.png",
      "href": "https://example.com/",
      "alt": "Example text"
    }
  ],
  "links": [
    {
      "href": "https://example.com/",
      "text": "Link text"
    }
  ],
  "event_action": "trigger",
  "client": "Sample Monitoring Service",
  "client_url": "https://monitoring.example.com"
}

Events API v2는 routing_key가 필요해요. 아무 PagerDuty 서비스에 Events API v2 통합을 만들어 routing key를 얻을 수 있고, 규칙셋의 integration key로도 alert 이벤트를 보낼 수 있어요.

Webhook

Webhook을 통해 PagerDuty는 계정 안에서 일어나는 액션에 대한 정보를 HTTP 요청을 받을 수 있는 어떤 소프트웨어로든 보내줘요. 현재 최신 버전은 V3예요. V3는 이전 버전보다 인시던트 우선순위·응답자 변경을 알려주는 추가 이벤트 타입과 추가 필터링 기능을 제공해요.

V3 webhook을 시작하려면 Webhook Subscriptions API로 webhook 구독을 만들어야 해요. 기존 V1/V2 webhook 확장을 쓰고 있다면 마이그레이션 가이드나 마이그레이션 스크립트를 이용해 V3 webhook 구독으로 옮길 수 있어요.

V3 webhook은 세 가지 주요 구성 요소를 담은 webhook subscription으로 설정돼요.

1. 관심 있는 아웃바운드 이벤트 타입의 집합
2. 전달할 이벤트의 필터(filter) 또는 범위(scope)
3. 매칭되는 이벤트를 webhook으로 보내는 전달 방식(delivery method)

Webhook 구독 생성 요청 예시:

{
  "webhook_subscription": {
    "delivery_method": {
      "type": "http_delivery_method",
      "url": "https://example.com/receive_a_pagerduty_webhook",
      "custom_headers": [
        {
          "name": "your-header-name",
          "value": "your-header-value"
        }
      ]
    },
    "description": "Sends PagerDuty v3 webhook events somewhere interesting.",
    "events": [
      "incident.acknowledged",
      "incident.annotated",
      "incident.delegated",
      "incident.escalated",
      "incident.priority_updated",
      "incident.reassigned",
      "incident.reopened",
      "incident.resolved",
      "incident.responder.added",
      "incident.responder.replied",
      "incident.status_update_published",
      "incident.triggered",
      "incident.unacknowledged"
    ],
    "filter": {
      "id": "P393ZNQ",
      "type": "service_reference"
    },
    "type": "webhook_subscription"
  }
}

• custom_headers: webhook 구독의 custom_headers는 목적지 URL로 보내는 페이로드에 포함될 선택적 헤더를 정의해요. 헤더 값은 GET 요청에서는 redact되지만 webhook으로 endpoint에 전달될 때는 redact되지 않아요. 모든 헤더 이름은 구독 안에서 유일해야 해요.
• events: 어떤 이벤트 타입이 webhook을 만들지 정의해요. 목적지가 일부 이벤트만 원하면 전체 이벤트 타입 중 일부만 지정할 수 있어요.
• filter: webhook 구독의 filter는 전달할 이벤트 범위를 정의해요.

더 알아보기 (Learn more)

• 공식 문서