웹훅 알림 설정

웹훅 알림 설정 (Configure webhook notifications)

연락처 포인트의 webhook 통합을 사용해 내 시스템으로 알림을 보낼 수 있어요. 알림이 트리거되면 알림 세부 정보와 추가 데이터를 담은 JSON 요청을 webhook 엔드포인트로 보냅니다. 이 통합은 시스템에 알림을 통합하는 유연한 방법이에요.

출처: 문서

본문

webhook 통합은 시스템에 알림을 통합하는 유연한 방법입니다. 알림이 트리거되면 알림 세부 정보와 추가 데이터가 담긴 JSON 요청을 webhook 엔드포인트로 보냅니다.

연락처 포인트용 webhook 구성

1. Alerts & IRM → Alerting → Notification configuration 으로 이동한 다음 Contact points 탭을 선택합니다.
2. + Add contact point → 이름 입력 → Integration 목록에서 Webhook 선택.
3. URL 필드에 Webhook URL을 붙여넣습니다.
4. (선택) 추가 설정 구성.
5. Save contact point 클릭.

연락처 포인트 테스트·알림 활성화 방법은 Configure contact points 문서를 참고하세요.

Webhook 설정 (Webhook settings)

주의: URL은 보안 필드가 아니에요. 일반 텍스트로 저장되며 연락처 포인트를 다시 읽을 때 마스킹되지 않습니다. 토큰·비밀번호 같은 시크릿을 URL에 포함하는 것은 본인 책임입니다. webhook 엔드포인트에 인증하려면 선택 설정의 authorization 필드(예: Basic Authentication 또는 Authorization 요청 헤더)를 사용하세요. 이 필드들은 안전하게 저장되고 읽을 때 마스킹됩니다.

선택 설정 (Optional settings)

참고: HTTP Basic Authentication 또는 Authorization 요청 헤더 중 하나만 구성할 수 있어요 — 둘 다는 안 됩니다.

HMAC 서명 (HMAC signature)

HMAC 서명으로 웹훅 알림을 보호해 요청의 신뢰성과 무결성을 검증할 수 있어요. 활성화하면 Grafana가 공유 시크릿으로 HMAC-SHA256을 사용해 웹훅 페이로드에 서명합니다.

HMAC 서명 구성 시 Grafana는 시크릿 키로 HMAC-SHA256 서명을 생성합니다. 타임스탬프 헤더가 지정되면 Unix 타임스탬프가 서명 계산에 포함됩니다. 서명은 다음과 같이 계산됩니다:

HMAC(timestamp + ":" + body)

타임스탬프는 지정된 헤더로 전송됩니다. 타임스탬프 헤더가 없으면 서명은 요청 본문만으로 계산됩니다. 서명은 지정된 서명 헤더에 hex 인코딩 문자열로 전송됩니다.

요청 검증 (Validate a request):

1. 헤더에서 서명 추출(기본 X-Grafana-Alerting-Signature).
2. 타임스탬프 헤더를 구성했다면 타임스탬프 값을 추출해 재생 공격 방지를 위해 최근 것인지 확인.
3. 예상 서명 계산: 공유 시크릿으로 HMAC-SHA256 해시 생성 → 타임스탬프를 사용한다면 요청 본문 앞에 콜론(:)이 포함된 타임스탬프 포함 → 원시 요청 본문 해시 → 결과를 hex 문자열로 변환.
4. 계산된 서명을 요청 헤더의 것과 비교.

템플릿을 사용한 선택 설정 (Optional settings using templates)

JSON 페이로드에 커스텀 데이터를 포함하려면 다음 설정을 사용합니다. 두 옵션 모두 알림 템플릿 지원.

선택 알림 설정 (Optional notification settings):

기본 JSON 페이로드 (Default JSON payload)

두 개의 발화 알림이 포함된 웹훅 알림 페이로드 예시:

{
  "receiver": "My Super Webhook",
  "status": "firing",
  "orgId": 1,
  "alerts": [
    {
      "status": "firing",
      "labels": { "alertname": "High memory usage", "team": "blue", "zone": "us-1" },
      "annotations": { "description": "The system has high memory usage", "runbook_url": "https://myrunbook.com/runbook/1234", "summary": "This alert was triggered for zone us-1" },
      "startsAt": "2021-10-12T09:51:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/1afz29v7z/edit",
      "fingerprint": "c6eadffa33fcdf37",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": { "B": 44.23943737541908, "C": 1 }
    },
    {
      "status": "firing",
      "labels": { "alertname": "High CPU usage", "team": "blue", "zone": "eu-1" },
      "annotations": { "description": "The system has high CPU usage", "runbook_url": "https://myrunbook.com/runbook/1234", "summary": "This alert was triggered for zone eu-1" },
      "startsAt": "2021-10-12T09:56:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/d1rdpdv7k/edit",
      "fingerprint": "bc97ff14869b13e3",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": { "B": 44.23943737541908, "C": 1 }
    }
  ],
  "groupLabels": {},
  "commonLabels": { "team": "blue" },
  "commonAnnotations": {},
  "externalURL": "https://play.grafana.org/",
  "version": "1",
  "groupKey": "{}:{}",
  "truncatedAlerts": 0,
  "title": "[FIRING:2]  (blue)",
  "state": "alerting",
  "message": "**Firing**\n\nLabels:\n - alertname = T2 ..."
}

Body: 웹훅 알림의 JSON 페이로드는 다음 key-value 쌍을 포함합니다:

다음 key-value 쌍도 JSON 페이로드에 포함되며 웹훅 설정의 알림 템플릿으로 구성할 수 있어요: title(string, 커스텀 제목), message(string, 커스텀 메시지).

Alert 객체: alerts 필드가 제공하는 알림 그룹에 포함된 알림을 나타냅니다.

Custom Payload: 이 옵션은 템플릿으로 웹훅 페이로드를 완전히 커스터마이즈합니다. 웹훅 요청의 구조·내용을 완전히 제어할 수 있어요.

참고: Custom Payload를 사용하면 Title 과 Message 필드는 무시됩니다(전체 페이로드 구조가 템플릿에 의해 결정). Custom Payload는 Grafana Cloud에서 아직 일반 제공(generally available) 되지 않았어요.

변수를 포함한 커스텀 페이로드 템플릿 예:

{
  "alert_name": "{{ .CommonLabels.alertname }}",
  "status": "{{ .Status }}",
  "environment": "{{ .Vars.environment }}",
  "custom_field": "{{ .Vars.custom_field }}"
}

JSON 템플릿 함수: 커스텀 페이로드 생성 시 유효한 JSON 구조를 만드는 데 도움이 되는 여러 템플릿 함수를 사용할 수 있어요. 사전(coll.Dict), 배열(coll.Slice, coll.Append) 생성, JSON 문자열·객체 간 변환(data.ToJSON, data.JSON) 등이 있습니다. 자세한 내용은 알림 템플릿 함수를 참고하세요.

JSON 헬퍼 함수 사용 예:

{{ define "webhook.custom.payload" -}}
  {{ coll.Dict
  "receiver" .Receiver
  "status" .Status
  "alerts" (tmpl.Exec "webhook.custom.simple_alerts" .Alerts | data.JSON)
  "groupLabels" .GroupLabels
  "commonLabels" .CommonLabels
  "commonAnnotations" .CommonAnnotations
  "externalURL" .ExternalURL
  "version" "1"
  "orgId"  (index .Alerts 0).OrgID
  "truncatedAlerts"  .TruncatedAlerts
  "groupKey" .GroupKey
  "state"  (tmpl.Inline "{{ if eq .Status \"resolved\" }}ok{{ else }}alerting{{ end }}" . )
  "allVariables"  .Vars
  "title" (tmpl.Exec "default.title" . )
  "message" (tmpl.Exec "default.message" . )
  | data.ToJSONPretty " "}}
{{- end }}

{{ define "webhook.custom.simple_alerts" -}}
  {{- $alerts := coll.Slice -}}
  {{- range . -}}
    {{ $alerts = coll.Append (coll.Dict
    "status" .Status
    "labels" .Labels
    "startsAt" .StartsAt
    "endsAt" .EndsAt
    ) $alerts}}
  {{- end -}}
  {{- $alerts | data.ToJSON -}}
{{- end }}

더 알아보기 (Learn more)

• 출처 문서: Configure webhook notifications
• 연락처 포인트 구성
• 알림 템플릿
• 알림 템플릿 함수
• Grafana Alerting 문서 홈