프로그래밍 처리 위해 HTTP POST 요청으로 웹훅 엔드포인트에 경고 알림 보내도록 Cloud Manager 구성할 수 있습니다. 웹훅을 사용하면 Cloud Manager 경고를 사용자 지정 모니터링 시스템, 사고 관리 플랫폼 또는 자동화 워크플로와 통합할 수 있습니다.
필요한 액세스 권한
Cloud Manager 웹훅과 통합하려면 프로젝트 에 대한 Project Monitoring Admin 액세스 있어야 합니다.
웹훅 통합 구성
MongoDB Cloud Manager 에서 Project Settings 페이지로 이동합니다.
아직 표시되지 않은 경우 탐색 표시줄의 Organizations 메뉴에서 원하는 프로젝트가 포함된 조직을 선택합니다.
아직 표시되지 않은 경우 탐색 표시줄의 Projects 메뉴에서 원하는 프로젝트를 선택합니다.
사이드바에서 Project Settings를 클릭합니다.
프로젝트 설정 페이지가 표시됩니다.
웹혹으로 경고를 보내려면 경고 알림을 구성합니다. 자세한 학습은 경고 설정 구성을 참조하세요.
요청 헤더
Cloud Manager 각 웹훅 요청 에 다음과 같은 HTTP headers 포함되어 있습니다.
Cloud Manager는 다양한 경고 상태를 구분하기 위해 X-MMS-Event 이라는 요청 헤더를 추가합니다. 이 헤더에 사용할 수 있는 값은 다음과 같습니다.
| 경고가 방금 열렸습니다. |
| 경고가 해결되었습니다. |
| 이전에 열린 경고는 여전히 열려 있습니다. |
| 경고가 승인되었습니다. |
| 경고가 유효하지 않게 되어 취소되었습니다. |
| '프라이머리 선출'과 같은 특정 시점 이벤트인 정보 경고를 나타냅니다. |
Webhook Secret 필드 에 키를 지정하면 MongoDB Cloud Manager X-MMS-Signature 요청 헤더를 추가합니다. 이 헤더에는 요청 본문의 기본64인코딩된 HMAC-SHA-1 서명이 포함되어 있습니다. MongoDB Cloud Manager 제공된 시크릿을 사용하여 서명을 생성합니다.
요청 본문
요청 본문에는 Cloud Manager API 경고 리소스 와 동일한 형식을 사용하는 JSON 문서 포함되어 있습니다. 페이로드에는 다음과 같은 키 필드가 포함됩니다.
id: 경고의 고유 식별자입니다.eventTypeName경고를 트리거하는 이벤트 유형입니다.created경고가 생성된 시간입니다.status: 경고 의 현재 상태( 예시:OPEN,CLOSED)입니다.humanReadable: 사람이 읽을 수 있는 경고 에 대한 설명입니다.
전체 필드 목록은 1개 경고 받기 엔드포인트 설명서를 참조하세요.
예시 웹훅 페이로드
다음 예시 지표 임계값 경고 에 대한 샘플 웹훅 페이로드를 보여줍니다.
{ "id": "5d1b6f8e8c2e4e2d3c4a5b6c", "groupId": "5d1b6f8e8c2e4e2d3c4a5b6d", "eventTypeName": "OUTSIDE_METRIC_THRESHOLD", "status": "OPEN", "created": "2024-01-15T10:30:00Z", "updated": "2024-01-15T10:30:00Z", "lastNotified": "2024-01-15T10:30:00Z", "humanReadable": "Disk space used on data partition is 95.2%.", "metricName": "DISK_PARTITION_SPACE_USED_DATA", "currentValue": { "number": 95.2, "units": "RAW" } }
웹훅 템플릿 사용자 지정
웹훅 알림에 webhookHeadersTemplate 및 webhookBodyTemplate 필드를 설정하여 웹훅 요청 헤더와 보디 컨텐츠를 사용자 지정할 수 있습니다. 각 템플릿은 ${field} 인터폴레이션을 지원합니다. Cloud Manager는 알림을 보내려고 할 때 경고 문서의 일치하는 필드의 값으로 각 ${field} 자리 표시자를 대체합니다.
경고 문서가 반환하는 ${eventTypeName}, ${clusterName}, ${status}, ${created} 등의 모든 필드를 인터폴레이션할 수 있습니다. 인터포레이션할 수 있는 필드의 완전한 목록은 Get One 경고 엔드포인트의 응답 필드를 참조하십시오.
예를 들어, 본문 템플릿 {"event": "${eventTypeName}", "cluster": "${clusterName}"} 은 Cloud Manager가 요청을 보내기 전에 각 위치 표시자를 경고 값으로 렌더링합니다.
렌더링된 본문은 유효한 JSON 이어야 하며 Content-Type: application/json 헤더와 함께 전송됩니다. 렌더링된 헤더는 각 헤더 이름을 해당 값에 매핑하는 JSON 객체 형성해야 합니다. Cloud Manager 웹훅 시크릿 또는 서명 헤더를 템플릿에 노출하지 않고 API 응답에서 두 템플릿 필드를 모두 수정합니다.
템플릿이 렌더링에 실패하거나 크기 제한을 초과하거나 잘못된 출력이 생성되는 경우 Cloud Manager 기본값 페이로드와 헤더를 대신 전송하면서 알림을 전달합니다.
경고를 저장하기 전에 렌더링된 결과를 미리 보려면 Post test message to webhook 버튼을 클릭합니다. 이 버튼을 클릭하면 샘플 경고 데이터에 대해 템플릿이 렌더링됩니다.
웹훅 요청 인증
Webhook Secret 필드 Cloud Manager 요청 확인을 위한 X-MMS-Signature 헤더를 생성하는 데에만 사용하는 시크릿을 저장합니다. Cloud Manager 시크릿을 인증 헤더 또는 베어러 토큰으로 직접 전송하지 않습니다.
웹훅 엔드포인트에 인증이 필요한 경우 다음 방법 중 하나를 사용하여 독립적으로 처리해야 합니다.
쿼리 매개변수: Webhook URL 에 인증 자격 증명을 쿼리 매개변수로 포함합니다. 예:
https://example.com/webhook?token=your-auth-tokenIP 액세스 목록: Cloud Manager IP 주소의 요청만 수락하도록 웹훅 엔드포인트를 구성합니다. 이 구성을 사용하면 Cloud Manager 만 엔드포인트에 요청을 보낼 수 있습니다.
역방향 프록시 또는 API 게이트웨이: 웹훅 엔드포인트에 요청을 전달하기 전에 인증 처리하는 역방향 프록시 또는 API 게이트웨이를 사용합니다.
웹훅 요청 확인
웹훅 요청 Cloud Manager 에서 시작되었는지 확인하려면 X-MMS-Signature 헤더의 유효성을 검사합니다.
웹훅 시크릿을 사용하여 요청 본문의 기본64 인코딩된 HMAC-SHA-1 서명을 계산합니다.
제한 사항
webhook 통합을 사용할 때 다음 제한 사항을 고려합니다.
경고 심각도 미포함
웹훅 페이로드에는 Cloud Manager 에서 구성한 경고 심각도 수준이 포함되어 있지 않습니다. 구성된 심각도를 조회 하려면 웹훅 페이로드에서 alertConfigId를 사용하여 하나의 경고 구성 가져오기 엔드포인트를 추가로 호출합니다.
수동 테스트 경고 없음
Cloud Manager 테스트 경고를 수동으로 트리거하다 하는 방법을 제공하지 않습니다. 웹훅 엔드포인트를 테스트하려면 다음과 같이 트리거하다 하기 쉬운 조건으로 경고 일시적으로 설정하다 수 있습니다.
테스트 배포서버 의 디스크 공간 부족 임계값.
여러 연결을 열어 trigger할 수 있는 연결 카운트 임계값입니다.
테스트 복제본 세트의 복제 지연 임계값.
웹훅이 경고를 정상적으로 수신하는 것을 확인한 후 테스트 경고 구성을 삭제할 수 있습니다.
방화벽 구성
방화벽 에서 IP 액세스 목록 구성해야 하는 경우 Cloud Manager 웹훅 엔드포인트와 통신할 수 있도록 Cloud Manager IP 주소에서 액세스 허용하세요.
웹훅 전달 문제 해결
웹훅이 경고를 수신하지 않은 경우: