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 を使用します。

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

アクションは、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 チェックボックスをオンにし、アクションの操作設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。