4 Webhook

概要

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

統合

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

ここに記載されているサービスに加えて、Zabbix は Spiceworks と統合できます（webhook は不要です）。 Zabbix の通知を Spiceworks のチケットに変換するには、email media type を作成し、指定した 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 オプションを参照）。

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

関連情報: 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 チェックボックスをオンにすると、作成された外部チケットへのリンクを含む イベントメニュー の項目を追加します。
この項目は、有効でこのチェックボックスがオンになっている各 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 属性値は変更されません。

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