4 Webhook

원본 보기

4 Webhook

개요

webhook 미디어 타입은 헬프데스크 시스템, 채팅 또는 메신저와 같은 외부 소프트웨어와의 직접적인 통합을 위해 사용자 정의 JavaScript 코드를 사용하여 HTTP 호출을 하는 데 유용합니다. Zabbix에서 제공하는 통합을 가져오거나 처음부터 사용자 정의 통합을 생성할 수 있습니다.

연동

다음 연동을 사용하여 Zabbix 알림을 다음 서비스로 전송하기 위한 사전 정의된 웹훅 미디어 타입을 사용할 수 있습니다:

여기에 나열된 서비스 외에도 Zabbix는 Spiceworks와 연동할 수 있습니다 (웹훅 불필요). Zabbix 알림을 Spiceworks 티켓으로 변환하려면 이메일 미디어 타입을 생성하고 지정된 Zabbix 사용자의 프로필 설정에 Spiceworks 헬프데스크 이메일 주소(예: help\@zabbix.on.spiceworks.com)를 입력하십시오.

설정

웹훅 통합을 사용하기 시작하려면:

  1. 다운로드한 Zabbix 버전의 templates/media 디렉터리에서 필요한 .yaml 파일을 찾거나 Zabbix git repository에서 다운로드하세요.
  2. 파일을 Zabbix 설치에 가져오기하세요. 웹훅이 미디어 유형 목록에 나타납니다.
  3. Readme.md 파일의 지침에 따라 웹훅을 설정하세요(위의 웹훅 이름을 클릭하면 Readme.md에 빠르게 액세스할 수 있습니다).

사용자 정의 웹훅을 처음부터 생성하려면:

  1. Alerts > Media types로 이동하세요.
  2. Create media type을 클릭하세요.

Media type 탭에는 이 미디어 유형에 특정한 다양한 속성이 포함되어 있습니다:

모든 필수 입력 필드는 빨간색 별표로 표시됩니다.

다음 매개변수는 웹훅 미디어 유형에 특정됩니다:

매개변수 설명
Parameters 웹훅 변수를 속성과 값 쌍으로 지정하세요.
미리 구성된 웹훅의 경우 매개변수 목록은 서비스에 따라 다릅니다. 매개변수 설명은 웹훅의 Readme.md 파일을 확인하세요.
새로운 웹훅의 경우 몇 가지 공통 변수가 기본적으로 포함되어 있습니다(URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}). 필요에 따라 유지하거나 제거하세요.

웹훅 매개변수는 사용자 매크로, 문제 알림에서 지원되는 모든 매크로, 그리고 추가적으로 {ALERT.SENDTO}, {ALERT.SUBJECT}, {ALERT.MESSAGE} 매크로를 지원합니다.

HTTP 프록시를 지정하면 해당 필드는 항목 구성 HTTP proxy 필드와 동일한 기능을 지원합니다. 프록시 문자열은 사용되는 프록시 종류를 지정하기 위해 [scheme]://으로 접두사를 붙일 수 있습니다(예: https, socks4, socks5; 문서 참조).
Script 매개변수 필드를 클릭하거나 옆의 연필 아이콘을 클릭할 때 열리는 모달 편집기에서 JavaScript 코드를 입력하세요. 이 코드는 웹훅 작업을 수행합니다.
스크립트는 매개변수-값 쌍을 받는 함수 코드입니다. 값은 JSON.parse() 메서드를 사용하여 JSON 객체로 변환되어야 합니다. 예: var params = JSON.parse(value);.

코드는 모든 매개변수에 액세스할 수 있고, HTTP GET, POST, PUT, DELETE 요청을 수행할 수 있으며, CONNECT, PATCH, HEAD, OPTIONS, TRACE와 같은 추가 메서드를 지원하고, HTTP 헤더와 요청 본문을 제어할 수 있습니다.
스크립트는 반드시 return 연산자를 포함해야 하며, 그렇지 않으면 유효하지 않습니다. OK 상태와 함께 선택적 태그 목록 및 태그 값을 반환하거나(Process tags 옵션 참조) 오류 문자열을 반환할 수 있습니다.

스크립트는 알림이 생성된 후에만 실행됩니다. 스크립트가 태그를 반환하고 처리하도록 구성된 경우, 스크립트가 아직 실행될 시간이 없었기 때문에 이러한 태그는 초기 문제 메시지와 복구 메시지의 {EVENT.TAGS} 및 {EVENT.RECOVERY.TAGS} 매크로에서 해결되지 않습니다.
참고: 각 스크립트가 자체 데이터에서 작동하고 동시 호출 간 충돌을 방지하기 위해 전역 변수(예: global = 1) 대신 지역 변수(예: var local = 1) 사용을 권장합니다(알려진 이슈 참조).

참조: 웹훅 개발 가이드라인, 웹훅 스크립트 예제, 추가 JavaScript 객체.
Timeout JavaScript 실행 타임아웃(1-60초, 기본값 30초).
시간 접미사가 지원됩니다(예: 30s, 1m).
Process tags 반환된 JSON 속성 값을 태그로 처리하려면 체크박스를 표시하세요. 이러한 태그는 기존 문제 태그에 추가됩니다.
웹훅 태그를 사용할 때 웹훅은 최소한 빈 태그 객체를 포함하는 JSON 객체를 반환해야 합니다: var result = {tags: {}};
반환될 수 있는 태그 예제: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Include event menu entry 생성된 외부 티켓으로 연결되는 항목을 이벤트 메뉴에 포함하려면 체크박스를 표시하세요.
활성화되고 이 체크박스가 표시된 각 웹훅에 대해 항목이 포함됩니다. Menu entry name 및 Menu entry URL 매개변수에 {EVENT.TAGS.<tag name>} 매크로가 포함되어 있는 경우, 이러한 매크로가 해결될 수 있는 경우에만(즉, 이벤트에 이러한 태그가 정의되어 있는 경우) 항목이 포함됩니다.
표시된 경우, 웹훅은 다른 사용자에게 알림을 보내는 데 사용되어서는 안 되며(대신 전용 사용자 생성 고려), 단일 문제 이벤트에 대해 여러 알림 작업에서 사용되어서는 안 됩니다.
Menu entry name 메뉴 항목 이름을 지정하세요.
{EVENT.TAGS.<tag name>} 매크로가 지원됩니다.
이 필드는 Include event menu entry가 표시된 경우에만 필수입니다.
Menu entry URL 메뉴 항목의 기본 URL을 지정하세요.
{EVENT.TAGS.<tag name>} 매크로가 지원됩니다.
이 필드는 Include event menu entry가 표시된 경우에만 필수입니다.

기본 메시지 및 알림 처리 옵션을 구성하는 방법에 대한 자세한 내용은 공통 미디어 유형 매개변수를 참조하세요.

웹훅이 기본 메시지를 사용하지 않더라도, 이 웹훅에서 사용하는 작업 유형에 대한 메시지 템플릿은 여전히 정의되어야 합니다.

테스트

구성된 웹훅 미디어 타입을 테스트하려면:

  1. 미디어 타입 목록에서 관련 웹훅을 찾습니다.
  2. 목록의 마지막 열에서 테스트를 클릭합니다(테스트 창이 열립니다).
  3. 필요에 따라 웹훅 매개변수 값을 편집합니다. 매크로를 예시 값으로 바꾸세요. 그렇지 않으면 매크로가 해결되지 않아 테스트가 실패합니다.
  4. 테스트를 클릭합니다.

테스트 창에서 값을 바꾸거나 삭제하는 것은 테스트 절차에만 영향을 주며, 실제 웹훅 속성 값은 변경되지 않습니다.

테스트 창을 벗어나지 않고 미디어 타입 테스트 로그 항목을 보려면 로그 열기를 클릭하세요(새 팝업 창이 열립니다).

웹훅 테스트가 성공한 경우:

  • "미디어 타입 테스트 성공." 메시지가 표시됩니다.
  • 서버 응답이 회색 응답 필드에 나타납니다.
  • 응답 타입(JSON 또는 String)이 응답 필드 아래에 지정됩니다.

웹훅 테스트가 실패한 경우:

  • "미디어 타입 테스트 실패." 메시지가 표시되고, 추가 실패 세부사항이 뒤따릅니다.

사용자 미디어

미디어 유형이 구성되면 사용자 > 사용자 섹션으로 이동하여 기존 사용자에게 webhook 미디어를 할당하거나 webhook을 나타내는 새 사용자를 생성합니다. 기존 사용자에 대한 사용자 미디어 설정 단계는 모든 미디어 유형에 공통되며, 미디어 유형 페이지에 설명되어 있습니다.

webhook이 티켓\메시지 ID를 저장하기 위해 태그를 사용하는 경우, 서로 다른 사용자에게 동일한 webhook을 미디어로 할당하는 것을 피하세요. 이는 webhook 오류를 발생시킬 수 있습니다(이벤트 메뉴 항목 포함 옵션을 활용하는 대부분의 webhook에 적용됩니다). 이 경우 webhook을 나타내는 전용 사용자를 생성하는 것이 모범 사례입니다:

  1. webhook 미디어 유형을 구성한 후 사용자 > 사용자 섹션으로 이동하여 webhook을 나타내는 전용 Zabbix 사용자를 생성합니다. 예를 들어, Slack webhook의 경우 사용자 이름을 Slack으로 지정합니다. 이 사용자는 Zabbix에 로그인하지 않으므로 미디어를 제외한 모든 설정은 기본값으로 둘 수 있습니다.
  2. 사용자 프로필에서 미디어 탭으로 이동하여 필요한 연락처 정보와 함께 webhook을 추가합니다. webhook이 보낼 대상 필드를 사용하지 않는 경우, 유효성 검사 요구사항을 우회하기 위해 지원되는 문자의 조합을 입력하세요.
  3. 이 사용자에게 알림을 보내야 하는 모든 호스트에 대해 최소한 읽기 권한을 부여합니다.

알림 동작을 구성할 때 작업 세부 정보의 사용자에게 보내기 필드에 이 사용자를 추가하면 Zabbix가 이 동작의 알림에 webhook을 사용하도록 지시합니다.

알림 액션 구성

액션은 웹훅을 통해 어떤 알림을 보낼지 결정합니다. 웹훅과 관련된 액션 구성 단계는 다른 모든 미디어 유형과 동일하지만 다음과 같은 예외 사항이 있습니다:

  • 웹훅이 웹훅 태그를 사용하여 티켓\메시지 ID를 저장하고 업데이트\해결 작업을 처리하는 경우, 단일 문제 이벤트에 대해 여러 알림 액션에서 동일한 웹훅을 사용하지 마세요. {EVENT.TAGS.<tag name>}이 존재하고 웹훅에서 업데이트되는 경우, 결과 값이 정의되지 않을 수 있습니다. 이를 방지하려면 업데이트된 값을 저장할 때 웹훅에서 새 태그 이름을 사용하세요. 이는 Zabbix에서 제공하는 Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad, Zendesk 웹훅과 이벤트 메뉴 항목 포함 옵션을 활용하는 대부분의 웹훅에 적용됩니다. 단, 단일 웹훅은 동일한 액션의 여러 작업이나 에스컬레이션 단계와 서로 다른 조건으로 인해 동일한 문제 이벤트에 의해 트리거되지 않는 다른 액션에서는 사용할 수 있습니다.
  • 내부 이벤트에 대한 액션에서 웹훅을 사용할 때는 사용자 정의 메시지 체크박스를 선택하고 액션 작업 구성에서 사용자 정의 메시지를 정의해야 합니다. 그렇지 않으면 알림이 전송되지 않습니다.

다음 단계는?