4 Webhook

概要

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

統合

以下の統合が利用可能で、定義済みの webhook メディアタイプを使用して Zabbix の通知を次のサービスへ送信できます。

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

設定

webhook統合の使用を開始するには、次の手順を実行します。

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

ゼロからカスタムwebhookを作成するには、次の手順を実行します。

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

メディアタイプタブには、このメディアタイプ固有のさまざまな属性が含まれています。

すべての必須入力フィールドには赤いアスタリスクが付いています。

次のパラメータは、webhookメディアタイプ固有のものです。

パラメータ 説明
パラメータ 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プロキシフィールドと同じ機能がサポートされます。使用するプロキシの種類（https、socks4、socks5など）を指定するには、プロキシ文字列の先頭に[scheme]://を付けます（ドキュメントを参照）。
スクリプト パラメータフィールド内、またはその横にある鉛筆アイコンをクリックすると開くモーダルエディターに、JavaScriptコードを入力します。このコードによってwebhook操作が実行されます。
スクリプトは、パラメータと値のペアを受け取る関数コードです。値は、例えばvar params = JSON.parse(value);のように、JSON.parse()メソッドを使用してJSONオブジェクトに変換する必要があります。

コードはすべてのパラメータにアクセスでき、HTTP GET、POST、PUT、DELETEリクエストを実行できます。また、CONNECT、PATCH、HEAD、OPTIONS、TRACEなどの追加メソッドをサポートし、HTTPヘッダーとリクエスト本文を制御できます。
スクリプトにはreturn演算子を含める必要があります。含まれていない場合、スクリプトは有効になりません。スクリプトは、オプションのタグとタグ値の一覧（タグの処理オプションを参照）を伴うOKステータス、またはエラー文字列を返すことができます。

スクリプトはアラートの作成後にのみ実行されることに注意してください。スクリプトがタグを返して処理するように設定されている場合でも、初期障害メッセージおよび復旧メッセージの{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:<no value>
イベントメニューエントリを含める 作成された外部チケットへのリンクを含むエントリをイベントメニューに追加するには、チェックボックスを選択します。
有効になっていて、このチェックボックスが選択されている各webhookについて、エントリが追加されます。メニューエントリ名およびメニューエントリURLパラメータに{EVENT.TAGS.<tag name>}マクロが含まれている場合、これらのマクロを解決できる場合（つまり、イベントにこれらのタグが定義されている場合）にのみエントリが追加されます。
選択した場合、このwebhookを異なるユーザーへの通知送信に使用しないでください（代わりに専用ユーザーの作成を検討してください）。また、単一の障害イベントに対する複数のアクションで使用しないでください。
メニューエントリ名 メニューエントリ名を指定します。
{EVENT.TAGS.<tag name>}マクロがサポートされています。
イベントメニューエントリを含めるが選択されている場合、このフィールドは必須です。
メニューエントリURL メニューエントリのリンク先URLを指定します。
{EVENT.TAGS.<tag name>}マクロがサポートされています。
イベントメニューエントリを含めるが選択されている場合、このフィールドは必須です。

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

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

テスト

設定済みの webhook メディアタイプをテストするには、次の手順を実行します。

  1. 一覧 から該当する webhook を見つけます。
  2. 一覧の最後の列にある Test をクリックします（テストウィンドウが開きます）。
  3. 必要に応じて webhook パラメータの値を編集します。
    マクロは例の値に置き換えてください。置き換えない場合、マクロは解決されず、テストは失敗します。
  4. Test をクリックします。

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

Web メディアタイプのテストログエントリをテストウィンドウを離れずに表示するには、Open log をクリックします（新しいポップアップウィンドウが開きます）。

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

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

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

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

ユーザーメディア

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

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 を使用します。

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

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

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