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. 障害 > メディアタイプ に移動します。
  2. メディアタイプの作成 をクリックします。

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

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

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 オプションを参照）。

復旧イベント（自動生成されたもの、または手動クローズの結果として生成されたもののいずれも）はサーバーによって作成され、解決済みイベントタグ（テンプレート、ホスト、トリガーから継承されたタグを含む）を含みます。webhook スクリプトは障害が作成された後に実行されるため、webhook スクリプトが返すタグは初回の障害作成後にのみ追加され、初回の障害メッセージや即時復旧メッセージの {EVENT.TAGS} および {EVENT.RECOVERY.TAGS} マクロには含まれません。
Note: 各スクリプトがそれぞれ独自のデータで動作し、同時呼び出し間の競合を避けるため、グローバル変数（例: 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 について項目が追加されます。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 がオンの場合にのみ必須です。

既定メッセージと障害処理オプションの設定方法については、common media type parameters を参照してください。

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

テスト

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

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

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

テストウィンドウを離れずにメディアタイプのテストログエントリを表示するには、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つのウェブフックを使用することは可能です。
  • 内部イベント用のアクションでウェブフックを使用する場合、カスタムメッセージのチェックボックスを必ずマークし、アクション操作の設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。