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 パラメータは user macros、問題通知でサポートされるすべての macros、さらに {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 は異なるユーザーへの通知送信には使用しないでください（代わりに 専用ユーザー の作成を検討してください）。また、1 つの問題イベントに対する複数のアラートアクションで使用しないでください for a single problem event。
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つのウェブフックを使用することは可能です。
  • 内部イベント用のアクションでウェブフックを使用する場合、カスタムメッセージのチェックボックスを必ずマークし、アクション操作の設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。