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をクリックします。
  3. フォームにwebhookメディアタイプのパラメータを入力します。

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プロキシフィールドと同じ機能を使用できます。プロキシ文字列の先頭に[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演算子を含める必要があります。含まれていない場合、スクリプトは有効になりません。スクリプトは、オプションのタグとタグ値の一覧を伴うOKステータス（Process tagsオプションを参照）またはエラー文字列を返すことができます。

復旧イベント（自動的に生成されたもの、手動クローズの結果として生成されたものを問わず）はサーバーによって作成され、解決済みイベントタグ（テンプレート、ホスト、トリガーから継承されたタグを含む）が含まれます。webhookスクリプトはアラートの作成後に実行されるため、webhookスクリプトが返すタグは初回アラートの作成後にのみ追加され、初回の障害メッセージまたは即時復旧メッセージの{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. 一覧の最後の列にあるテストをクリックします（テストウィンドウが開きます）。
  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を使用します。

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

アクションは、webhook を介してどの通知を送信するかを決定します。 webhook を含む アクションの設定 の手順は、次の例外を除き、他のすべてのメディアタイプと同じです。

  • webhook がチケット\メッセージ ID を保存し、更新\解決の操作を処理するために webhook タグ を使用する場合、1 つの障害イベントに対して複数のアラートアクションで同じ 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 は、同一のアクション内の複数の操作またはエスカレーションステップで使用できます。また、異なる 条件 により同じ障害イベントではトリガーされない別のアクションでも使用できます。
  • 内部イベント 用のアクションで webhook を使用する場合は、必ず Custom message チェックボックスをオンにし、アクションの操作設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。