4 Webhook

概要

Webhookメディアタイプは、カスタムJavaScriptコードを使用してHTTPコールを行うのに便利で、ヘルプデスクシステム、チャット、メッセンジャーなどの外部ソフトウェアとの簡単な統合が可能です。 Zabbixが提供するインテグレーションをインポートするか、独自のインテグレーションをゼロから作成することができます。

連携

以下の連携が利用可能で、定義済みの webhook メディアタイプを使用して、Zabbix通知を次の宛先に送信できます。

ここに記載されているサービスに加えて、ZabbixはSpiceworksとも連携できます（webhook は不要です）。 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メディアタイプ固有のものです。

Parameter Description
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。詳細はdocumentationを参照してください）。
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ステータス、またはエラー文字列を返すことができます。

復旧イベント（自動生成されたもの、または手動クローズの結果として生成されたもののいずれも）はサーバーによって作成され、解決済みイベントタグ（テンプレート、ホスト、トリガーから継承されたタグを含む）が含まれます。webhookスクリプトはアラート作成後に実行されるため、webhookスクリプトが返したタグは最初のアラート作成後にのみ追加され、初回の障害メッセージまたは直後の復旧メッセージの {EVENT.TAGS} および {EVENT.RECOVERY.TAGS} マクロには含まれません。
注意: 各スクリプトが自身のデータのみを扱い、同時呼び出し間の競合を避けるため、グローバル変数（例: global = 1）ではなくローカル変数（例: var local = 1）を使用することを推奨します（既知の問題を参照）。

以下も参照してください: Webhook development guidelines、Webhook script examples、Additional JavaScript objects。
Timeout JavaScriptの実行タイムアウト（1-60s、デフォルトは30s）。
時間のサフィックスをサポートしています。例: 30s、1m。
Process tags 返されたJSONプロパティ値をタグとして処理するには、このチェックボックスをオンにします。これらのタグは既存の障害タグに追加されます。
webhook tagsを使用する場合、webhookは少なくとも空の tags オブジェクトを含むJSONオブジェクトを返す必要があることに注意してください: var result = {tags: {}};
返すことができるタグの例: jira-id:prod-1234、responsible:John Smith、processed:<no value>
Include event menu entry 作成された外部チケットへのリンクをevent menuに含めるには、このチェックボックスをオンにします。
有効化されていて、このチェックボックスがオンになっている各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. 一覧の最終列にあるテストをクリックします(テスト用ウィンドウが開きます)。
  3. 必要に応じてWebhookパラメータの値を編集します。 マクロを例示値に置き換えてください。そうしないとマクロが解決されず、テストが失敗します。
  4. テストをクリックします。

テストウィンドウで値を置き換えたり削除したりしても、テスト手順のみに影響し、実際のWebhook属性値は変更されません。

テストウィンドウを閉じずにメディアタイプのテストログエントリを表示するには、ログを開くをクリックします(新しいポップアップウィンドウが開きます)。

Webhookテストが成功した場合：

  • "Media type test successful." メッセージが表示されます。
  • サーバーのレスポンスがグレーの Response フィールドに表示されます。
  • レスポンスタイプ（JSONまたはString）が Response フィールドの下に表示されます。

Webhookテストが失敗した場合:

  • "メディアタイプのテストに失敗しました。" というメッセージが表示され、続いて追加の失敗の詳細が表示されます。

ユーザーメディア

メディアタイプを設定したら、ユーザー > ユーザー セクションに移動し、既存のユーザーにWebhookメディアを割り当てるか、Webhookを表す新しいユーザーを作成します。 既存のユーザーのユーザーメディアの設定手順は、すべてのメディアタイプに共通であり、メディアタイプのページで説明されています。

Webhookがタグを使用してチケットやメッセージIDを保存する場合、同じWebhookを異なるユーザーにメディアとして割り当てると、Webhookエラーが発生する可能性があるため避けてください（イベントメニューエントリを含める オプションを利用する大多数のWebhookに該当します）。 この場合、Webhookを表す専用のユーザーを作成するのがベストプラクティスです:

  1. Webhookメディアタイプを設定した後、ユーザー > ユーザー セクションに移動し、Webhookを表す専用のZabbixユーザーを作成します。たとえば、Slack Webhookの場合はユーザー名をSlackにします。 このユーザーはZabbixにログインしないため、メディア以外のすべての設定はデフォルトのままでかまいません。
  2. ユーザープロファイルのメディアタブで、必要な連絡先情報を指定してWebhookを追加します。 Webhookが送信先フィールドを使用しない場合は、検証要件を回避するためにサポートされている任意の文字の組み合わせを入力してください。
  3. このユーザーに、アラートを送信する必要があるすべてのホストに対して、少なくとも読み取り権限を付与します。

アラートアクションを設定する際は、操作の詳細のユーザーへの送信フィールドにこのユーザーを追加します。これにより、Zabbixはこのアクションからの通知にWebhookを使用するようになります。

アラートアクションの設定

アクションは、どの通知をウェブフック経由で送信するかを決定します。 ウェブフックを含むアクションの設定手順は、以下の例外を除き、他のすべてのメディアタイプと同じです。

  • ウェブフックがチケットやメッセージIDの保存や更新・解決操作の処理にウェブフックタグを使用する場合、1つの問題イベントに対して同じウェブフックを複数のアラートアクションで使用しないでください。 {EVENT.TAGS.<tag name>}が存在し、ウェブフック内で更新された場合、その結果の値は未定義になります。 これを回避するには、更新された値を保存するためにウェブフックで新しいタグ名を使用してください。 これは、Zabbixが提供するJira、Jira Service Desk、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad、Zendeskのウェブフックおよびイベントメニューエントリを含めるオプションを利用するほとんどのウェブフックに該当します。 ただし、同じアクションの複数の操作やエスカレーションステップ、または異なる条件により同じ問題イベントでトリガーされない異なるアクションで、1つのウェブフックを使用することは可能です。
  • 内部イベント用のアクションでウェブフックを使用する場合、カスタムメッセージのチェックボックスを必ずマークし、アクション操作の設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。