webhook

概要

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

インテグレーション

以下のインテグレーションを利用できます。定義済みのwebhookメディアタイプを使用して、Zabbixの通知を次のサービスに送信できます。

ここに記載されているサービスに加えて、ZabbixはSpiceworksとも統合できます（webhookは不要です）。 Zabbixの通知をSpiceworksのチケットに変換するには、メールメディアタイプを作成し、指定したZabbixユーザーのプロファイル設定にSpiceworksヘルプデスクのメールアドレス（例: [email protected]）を入力します。

設定

webhook統合の使用を開始するには、次の手順を実行します。

  1. ダウンロードしたZabbixバージョンのtemplates/mediaディレクトリで必要な.yamlファイルを探すか、Zabbixのgitリポジトリからダウンロードします。
  2. ファイルをZabbixインストール環境にインポートします。
    webhookがメディアタイプの一覧に表示されます。
  3. Readme.mdファイルの手順に従ってwebhookを設定します（上記のwebhook名をクリックすると、Readme.mdにすばやくアクセスできます）。

ゼロからカスタムwebhookを作成するには、次の手順を実行します。

  1. アラート > メディアタイプに移動します。
  2. メディアタイプの作成をクリックします。
  3. フォームにwebhookメディアタイプのパラメータを入力します。

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

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

以下のパラメータは、webhookメディアタイプ固有のものです。

パラメータ 説明
パラメータ 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プロキシフィールドと同じ機能がサポートされます。プロキシ文字列の先頭に[scheme]://を付けて、使用するプロキシの種類（https、socks4、socks5など）を指定できます。ドキュメントを参照してください。
スクリプト パラメータフィールド内またはその横にある鉛筆アイコンをクリックすると開くモーダルエディターに、JavaScriptコードを入力します。このコードによってwebhook操作が実行されます。
スクリプトは、パラメータと値のペアを受け取る関数コードです。値は、例としてvar params = JSON.parse(value);のように、JSON.parse()メソッドを使用してJSONオブジェクトに変換する必要があります。

コードはすべてのパラメータにアクセスでき、HTTP GET、POST、PUT、DELETEリクエストを実行できます。また、CONNECT、PATCH、HEAD、OPTIONS、TRACEなどの追加メソッドをサポートし、HTTPヘッダーとリクエスト本文を制御できます。
スクリプトにはreturn演算子を含める必要があります。含まれていない場合、スクリプトは無効です。OKステータスと、オプションのタグおよびタグ値の一覧（タグの処理オプションを参照）またはエラー文字列を返すことができます。

リカバリイベント（自動的に生成されたもの、手動でクローズした結果として生成されたものを問わず）はサーバーによって作成され、解決済みイベントタグ（テンプレート、ホスト、トリガーから継承されたタグを含む）が含まれます。webhookスクリプトはアラートの作成後に実行されるため、webhookスクリプトが返すタグは初回のアラート作成後にのみ追加され、初回の障害メッセージまたは直後のリカバリメッセージの{EVENT.TAGS}および{EVENT.RECOVERY.TAGS}マクロには含まれません。
注: 各スクリプトが独自のデータを処理し、同時実行される呼び出し間の衝突を回避できるように、グローバル変数（例：global = 1）ではなくローカル変数（例：var local = 1）を使用することを推奨します。既知の問題を参照してください。

以下も参照してください：Webhook開発ガイドライン、Webhookスクリプトの例、追加のJavaScriptオブジェクト。
タイムアウト JavaScriptの実行タイムアウト（1～60秒、デフォルトは30秒）。
時間のサフィックスがサポートされます（例：30s、1m）。
タグの処理 返されたJSONプロパティ値をタグとして処理するには、チェックボックスを選択します。これらのタグは、既存の障害タグに追加されます。
webhookタグを使用する場合、webhookは少なくとも空のtagsオブジェクトを含むJSONオブジェクトを返す必要があります：var result = {tags: {}};
返すことができるタグの例：jira-id:prod-1234、responsible:John Smith、processed:<no value>
イベントメニューエントリを含める 作成された外部チケットへのリンクを含むエントリをイベントメニューに追加するには、チェックボックスを選択します。選択されている有効なwebhookごとにエントリが追加されます。メニューエントリ名およびメニューエントリURLパラメータに{EVENT.TAGS.<tag name>}マクロが含まれている場合、これらのマクロを解決できる場合（つまり、イベントにこれらのタグが定義されている場合）にのみエントリが追加されます。
選択した場合、webhookを異なるユーザーへの通知送信に使用しないでください（代わりに専用ユーザーの作成を検討してください）。また、webhookを単一の障害イベントに対する複数のアラートアクションで使用しないでください。
メニューエントリ名 メニューエントリ名を指定します。
{EVENT.TAGS.<tag name>}マクロがサポートされます。
イベントメニューエントリを含めるが選択されている場合にのみ、このフィールドは必須です。
メニューエントリURL メニューエントリのリンク先URLを指定します。
{EVENT.TAGS.<tag name>}マクロがサポートされます。
イベントメニューエントリを含めるが選択されている場合にのみ、このフィールドは必須です。

デフォルトメッセージとアラート処理オプションの設定方法については、共通メディアタイプパラメータを参照してください。

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

テスト

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

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

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

テストウィンドウを閉じずにメディアタイプのテストログエントリを表示するには、ログを開くをクリックします（新しいポップアップウィンドウが開きます）。

Webhookテストが成功した場合：

  • "Media type test successful." メッセージが表示されます。
  • サーバーのレスポンスがグレーの Response フィールドに表示されます。
  • レスポンスタイプ（JSONまたはString）が Response フィールドの下に表示されます。

Webhookテストが失敗した場合:

  • "メディアタイプのテストに失敗しました。" というメッセージが表示され、続いて追加の失敗の詳細が表示されます。

ユーザーメディア

メディアタイプを設定したら、ユーザー > ユーザー セクションに移動し、webhookメディアを既存のユーザーに割り当てるか、webhookを表す新しいユーザーを作成します。 既存のユーザーにユーザーメディアを設定する手順は、すべてのメディアタイプに共通で、メディアタイプページに記載されています。

webhookがチケット\メッセージIDの保存にタグを使用する場合、同じwebhookを異なるユーザーのメディアとして割り当てないでください。これによりwebhookエラーが発生する可能性があります（イベントメニューエントリを含めるオプションを使用する大半のwebhookに該当します）。 この場合、webhookを表す専用ユーザーを作成することをお勧めします。

  1. webhookメディアタイプを設定したら、ユーザー > ユーザー セクションに移動し、webhookを表す専用のZabbixユーザーを作成します。たとえば、Slack webhookの場合は、ユーザー名を Slack にします。 このユーザーはZabbixにログインしないため、メディア以外のすべての設定はデフォルトのままにできます。
  2. ユーザープロファイルで、メディア タブに移動し、必要な連絡先情報を指定してwebhookを追加します。 webhookが送信先フィールドを使用しない場合は、検証要件を満たすため、サポートされている文字を任意に組み合わせて入力します。
  3. アラートを送信する必要があるすべてのホストに対して、このユーザーに少なくとも読み取り権限を付与します。

アラートアクションを設定する際は、操作の詳細のユーザーに送信フィールドにこのユーザーを追加します。これにより、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 チェックボックスをオンにし、アクションの操作設定でカスタムメッセージを定義してください。 そうしないと、通知は送信されません。