Webhook

Zabbix v7.4번역일: 2026-09-09원본 보기

개요

Webhook 미디어 유형은 커스텀 JavaScript 코드를 사용해 HTTP 호출을 수행함으로써 헬프데스크 시스템, 채팅, 메신저 등 외부 소프트웨어와 손쉽게 연동할 수 있게 해줍니다. Zabbix에서 제공하는 통합을 가져오거나, 처음부터 커스텀 통합을 직접 만들 수 있습니다.

통합

Zabbix 알림을 다음 서비스로 전송할 수 있도록 사전 정의된 webhook 미디어 유형을 제공하는 통합들은 다음과 같습니다:

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

구성

webhook 통합을 사용하려면:

  1. 다운로드한 Zabbix 버전의 templates/media 디렉터리에서 필요한 .yaml 파일을 찾거나 Zabbix git 저장소에서 다운로드합니다.
  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 연산자가 포함되어야 하며, 그렇지 않으면 유효하지 않은 것으로 처리됩니다. 태그 및 태그 값 목록(Process tags 옵션 참조)과 함께 OK 상태를 반환하거나 오류 문자열을 반환할 수 있습니다.

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

참고: Webhook development guidelines, Webhook script examples, Additional JavaScript objects.
Timeout JavaScript 실행 시간 제한(1-60초, 기본값 30초).
시간 접미사를 지원합니다(예: 30s, 1m).
Process tags 반환된 JSON 속성 값을 태그로 처리하려면 체크박스를 선택합니다. 이 태그는 기존 문제 태그에 추가됩니다.
webhook 태그를 사용할 경우, webhook은 최소한 빈 tags 객체를 포함한 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이 사용하는 작업 유형에 대한 메시지 템플릿은 반드시 정의되어 있어야 합니다.

테스트

구성된 webhook 미디어 유형을 테스트하려면:

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

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

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

webhook 테스트가 성공한 경우:

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

webhook 테스트가 실패한 경우:

  • "Media type test failed." 메시지가 표시되고, 이어서 추가 실패 세부 정보가 표시됩니다.

사용자 미디어

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

webhook이 티켓\메시지 ID를 저장하기 위해 태그를 사용하는 경우, 동일한 webhook을 서로 다른 사용자의 미디어로 할당하지 마세요. 그렇게 하면 webhook 오류가 발생할 수 있습니다(Include event menu entry 옵션을 사용하는 대부분의 webhook에 해당됩니다). 이 경우 가장 좋은 방법은 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을 사용하게 됩니다.

알림 액션 구성

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

  • webhook이 티켓\메시지 ID를 저장하고 업데이트\해결 작업을 처리하기 위해 webhook 태그를 사용하는 경우, 단일 문제 이벤트에 대해 여러 알림 액션에서 동일한 webhook을 사용하지 마세요. {EVENT.TAGS.<tag name>}가 존재하고 webhook에서 업데이트되면, 결과 값은 정의되지 않은 상태가 됩니다. 이를 방지하려면 업데이트된 값을 저장할 때 webhook에서 새로운 태그 이름을 사용하세요. 이는 Zabbix에서 제공하는 Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad, Zendesk webhook과, Include event menu entry 옵션을 사용하는 대부분의 webhook에 해당됩니다. 다만, 동일한 webhook을 동일한 액션의 여러 작업(operation)이나 에스컬레이션 단계에서 사용하는 것, 그리고 서로 다른 조건으로 인해 동일한 문제 이벤트에서 트리거되지 않는 다른 액션에서 사용하는 것은 가능합니다.
  • 내부 이벤트에 대한 액션에서 webhook을 사용할 때는 Custom message 체크박스를 반드시 선택하고 액션 작업 구성에서 커스텀 메시지를 정의하세요. 그렇지 않으면 알림이 전송되지 않습니다.