문서

원본 보기

4 Webhook

개요

웹훅 미디어 타입은 헬프데스크 시스템, 채팅, 메신저와 같은 외부 소프트웨어와의 간단한 통합을 위해 사용자 정의 JavaScript 코드를 사용하여 HTTP 호출을 수행하는 데 유용합니다. Zabbix에서 제공하는 통합을 가져오거나 처음부터 사용자 정의 통합을 만들 수 있습니다.

통합

다음과 같은 통합이 제공되어 Zabbix 알림을 다음 서비스로 전송하기 위한 미리 정의된 웹훅 미디어 유형을 사용할 수 있습니다:

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

구성

webhook 통합을 사용하기 위해서는:

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

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

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

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

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

다음 매개변수는 webhook 미디어 타입에 특정합니다:

매개변수 설명
Parameters webhook 변수를 속성과 값 쌍으로 지정하세요.
사전 구성된 webhook의 경우 매개변수 목록은 서비스에 따라 달라집니다. 매개변수 설명은 webhook의 Readme.md 파일을 확인하세요.
새 webhook의 경우 몇 가지 공통 변수가 기본적으로 포함됩니다(URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}). 자유롭게 유지하거나 제거하세요.

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

HTTP 프록시를 지정하는 경우, 필드는 아이템 구성 HTTP proxy 필드와 같은 기능을 지원합니다. 프록시 문자열은 [scheme]://로 접두사를 붙여 사용할 프록시 종류를 지정할 수 있습니다(예: https, socks4, socks5; 문서 참조).
Script 매개변수 필드를 클릭하거나 옆에 있는 연필 아이콘을 클릭할 때 열리는 모달 에디터에서 JavaScript 코드를 입력하세요. 이 코드는 webhook 작업을 수행합니다.
스크립트는 매개변수 - 값 쌍을 받는 함수 코드입니다. 값은 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)를 사용하는 것이 각 스크립트가 자체 데이터로 작동하고 동시 호출 간의 충돌을 피하기 위해 권장됩니다(알려진 문제 참조).

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

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

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

테스트

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

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

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

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

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

  • "Media type test successful." 메시지가 표시됩니다.
  • 서버 응답이 회색 Response 필드에 나타납니다.
  • 응답 타입 (JSON 또는 String)이 Response 필드 아래에 지정됩니다.

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

  • "Media type test failed." 메시지가 표시되며, 추가적인 실패 세부사항이 함께 표시됩니다.

사용자 미디어

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

webhook이 티켓\메시지 ID를 저장하기 위해 태그를 사용하는 경우, 동일한 webhook을 서로 다른 사용자의 미디어로 할당하는 것을 피하십시오. 그렇게 하면 webhook 오류가 발생할 수 있습니다(Include event menu entry 옵션을 활용하는 대부분의 webhook에 적용됩니다). 이 경우 best practice는 webhook을 대표할 전용 사용자를 생성하는 것입니다:

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

알림 액션을 구성할 때 Operation details의 Send to users 필드에 이 사용자를 추가합니다 - 이렇게 하면 Zabbix에게 이 액션의 알림에 webhook을 사용하도록 지시합니다.

알림 액션 구성

액션은 웹훅을 통해 어떤 알림을 전송할지 결정합니다. 웹훅과 관련된 액션 구성 단계는 다음 예외사항을 제외하고는 다른 모든 미디어 유형과 동일합니다:

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