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 演算子を含める必要があります。含まれていない場合は無効になります。OKステータスと、任意でタグおよびタグ値の一覧（Process tags オプションを参照）を返すことも、エラー文字列を返すこともできます。

スクリプトはアラートが作成された後にのみ実行される点に注意してください。スクリプトがタグを返して処理するよう設定されている場合、スクリプトがまだ実行されていないため、これらのタグは初回の障害メッセージおよび復旧メッセージ内の {EVENT.TAGS} および {EVENT.RECOVERY.TAGS} マクロでは解決されません。
注: 各スクリプトが自身のデータのみを扱い、同時呼び出し間の競合を避けるため、グローバル変数（例: global = 1）ではなくローカル変数（例: var local = 1）を使用することを推奨します（known issuesを参照）。

以下も参照してください: Webhook development guidelines、Webhook script examples、Additional JavaScript objects。
Timeout JavaScriptの実行タイムアウト（1～60秒、デフォルトは30秒）。
時間の接尾辞をサポートします。例: 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について、1つのエントリが追加されます。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 フィールドに表示されます。
  • レスポンスタイプ（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 を使用するようになります。

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

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

  • webhook がチケット\メッセージIDの保存や更新\解決操作の処理のために webhook tags を使用する場合、単一の障害イベントに対して同じ 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 チェックボックスをオンにし、アクション操作の設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。