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

このコードはすべてのパラメータにアクセスでき、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は少なくとも空の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. 一覧の最後の列にあるTestをクリックします（テスト用ウィンドウが開きます）。
  3. 必要に応じてwebhookパラメータの値を編集します。 マクロは例の値に置き換えてください。そうしないと、マクロが展開されず、テストは失敗します。
  4. Testをクリックします。

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

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

webhookテストが成功した場合:

  • 「メディアタイプのテストに成功しました。」 メッセージが表示されます。
  • サーバーのレスポンスが灰色の Response フィールドに表示されます。
  • Response フィールドの下に、レスポンスタイプ（JSON または String）が表示されます。

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

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

ユーザーメディア

メディアタイプを設定したら、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 と、イベントメニューエントリを含める オプションを利用するほとんどの webhook に適用されます。 ただし、同じ webhook は、同一アクション内の複数の操作またはエスカレーションステップで使用できるほか、異なる条件により同じ障害イベントではトリガーされない別のアクションでも使用できます。
  • 内部イベント用のアクションで webhook を使用する場合は、アクション操作設定で カスタムメッセージ チェックボックスをオンにし、カスタムメッセージを定義してください。 そうしないと、通知は送信されません。