4 Webhook

概要

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

インテグレーション

以下のインテグレーションが利用可能であり、Zabbix通知をプッシュするための定義済みWebhookメディアタイプを使用できます:

ここに記載されているサービスに加えて、ZabbixはSpiceworksとも連携できます（Webhookは不要です）。 Zabbixの通知をSpiceworksのチケットに変換するには、メールメディアタイプを作成し、指定したZabbixユーザーのプロファイル設定でSpiceworksヘルプデスクのメールアドレス（例: [email protected]）を入力してください。

設定

Webhookインテグレーションの使用を開始するには:

ダウンロードしたZabbixバージョンのtemplates/mediaディレクトリで必要な.yamlファイルを探すか、Zabbixのgitリポジトリからダウンロードします。
ファイルをZabbixインストールにインポートします。 Webhookはメディアタイプの一覧に表示されます。
Readme.mdファイルの手順に従ってWebhookを設定します（上記のWebhook名をクリックするとReadme.mdにすぐアクセスできます）。

独自のWebhookをゼロから作成するには:

アラート > メディアタイプに移動します。
メディアタイプの作成をクリックします。

メディアタイプタブには、このメディアタイプ特有のさまざまな属性があります:

必須入力フィールドは赤いアスタリスクでマークされています。

Webhookメディアタイプ特有のパラメータは以下の通りです:

パラメータ	説明
パラメータ	Webhookの変数を属性と値のペアで指定します。事前設定されたWebhookの場合、パラメータのリストはサービスによって異なります。パラメータの説明はWebhookのReadme.mdファイルを確認してください。新しいWebhookの場合、いくつかの共通変数がデフォルトで含まれています（URL:<空>, HTTPProxy:<空>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}）。そのまま残すか削除してください。 Webhookパラメータはユーザーマクロ、問題通知でサポートされているすべてのマクロに加え、{ALERT.SENDTO}、{ALERT.SUBJECT}、{ALERT.MESSAGE}マクロをサポートします。 HTTPプロキシを指定する場合、このフィールドはアイテム設定のHTTPプロキシフィールドと同じ機能をサポートします。プロキシ文字列は、どの種類のプロキシを使用するかを指定するために`[scheme]://`をプレフィックスとして付けることができます（例: https, socks4, socks5; ドキュメントを参照）。
スクリプト	パラメータフィールドをクリックするか、その横の鉛筆アイコンをクリックすると開くモーダルエディタにJavaScriptコードを入力します。このコードがWebhook操作を実行します。スクリプトはパラメータ-値のペアを受け取る関数コードです。値はJSON.parse()メソッドを使用してJSONオブジェクトに変換する必要があります。例: `var params = JSON.parse(value);`。コードはすべてのパラメータにアクセスでき、HTTP GET、POST、PUT、DELETEリクエストを実行でき、HTTPヘッダーやリクエストボディを制御できます。スクリプトにはreturn演算子が含まれている必要があります。そうでない場合は無効になります。OKステータスとオプションでタグとタグ値のリスト（タグの処理オプションを参照）またはエラー文字列を返すことができます。リカバリエベント（自動生成または手動クローズの結果として生成）はサーバーによって作成され、解決済みイベントタグ（テンプレート、ホスト、トリガーから継承されたタグを含む）を含みます。Webhookスクリプトはアラート作成後に実行されるため、Webhookスクリプトで返されたタグは初回アラート作成後にのみ追加され、初回の問題メッセージや即時リカバリーメッセージの{EVENT.TAGS}および`{EVENT.RECOVERY.TAGS}`マクロには存在しません。注意: 各スクリプトが独自のデータで動作し、同時呼び出し間の衝突を回避するために、グローバル変数（例: `global = 1`）ではなくローカル変数（例: `var local = 1`）を使用することを推奨します（既知の問題を参照）。参考: Webhook開発ガイドライン、Webhookスクリプト例、追加のJavaScriptオブジェクト。
タイムアウト	JavaScript実行のタイムアウト（1-60秒、デフォルト30秒）。 30s、1mなどの時間サフィックスがサポートされています。
タグの処理	返されたJSONプロパティ値をタグとして処理するにはチェックボックスをマークします。これらのタグは既存の問題タグに追加されます。 Webhookタグを使用する場合、Webhookは少なくとも空のtagsオブジェクトを含むJSONオブジェクトを返す必要があります: `var result = {tags: {}};` 返すことができるタグの例: jira-id:prod-1234、responsible:John Smith、processed:<値なし>
イベントメニューエントリを含める	作成された外部チケットへのリンクを含むイベントメニューにエントリを含めるにはチェックボックスをマークします。有効でこのチェックボックスがマークされている各Webhookについてエントリが含まれます。メニューエントリ名およびメニューエントリURLパラメータに{EVENT.TAGS.<tag name>}マクロが含まれている場合、これらのマクロが解決できる場合（つまり、イベントにこれらのタグが定義されている場合）にのみエントリが含まれます。マークされている場合、Webhookは異なるユーザーへの通知送信には使用しないでください（代わりに専用ユーザーの作成を検討してください）し、単一の問題イベントに対する複数のアラートアクションで使用しないでください。
メニューエントリ名	メニューエントリ名を指定します。 {EVENT.TAGS.<tag name>}マクロがサポートされています。このフィールドはイベントメニューエントリを含めるがマークされている場合のみ必須です。
メニューエントリURL	メニューエントリの基礎となるURLを指定します。 {EVENT.TAGS.<tag name>}マクロがサポートされています。このフィールドはイベントメニューエントリを含めるがマークされている場合のみ必須です。

デフォルトメッセージやアラート処理オプションの設定方法の詳細については、共通のメディアタイプパラメータを参照してください。

Webhookがデフォルトメッセージを使用しない場合でも、このWebhookで使用される操作タイプのメッセージテンプレートは定義する必要があります。

テスト

設定済みのWebhookメディアタイプをテストするには:

メディアタイプの一覧から該当するWebhookを探します。
一覧の最終列にあるテストをクリックします(テスト用ウィンドウが開きます)。
必要に応じてWebhookパラメータの値を編集します。マクロを例示値に置き換えてください。そうしないとマクロが解決されず、テストが失敗します。
テストをクリックします。

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

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

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

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

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

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

ユーザーメディア

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

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

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

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

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

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

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

Documentation

4 Webhook

概要

インテグレーション

設定

テスト

ユーザーメディア

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