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 ステータスに加えて、任意のタグとタグ値の一覧を返すことも、エラー文字列を返すこともできます（タグの処理 オプションを参照）。

なお、スクリプトが実行されるのはアラート作成後のみです。スクリプトがタグを返して処理するように設定されている場合でも、初期の障害メッセージおよび復旧メッセージ内の {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属性値は変更されません。

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

webhookテストが成功した場合:

  • 「メディアタイプのテストに成功しました。」 メッセージが表示されます。
  • サーバーのレスポンスが灰色の Response フィールドに表示されます。
  • Response フィールドの下に、レスポンスタイプ（JSON または String）が表示されます。

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

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

ユーザーメディア

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

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 タグ を使用している場合、単一の障害イベントに対して複数のアラートアクションで同じ webhook を使用しないでください。 {EVENT.TAGS.<tag name>} が存在し、webhook 内で更新されると、その結果の値は未定義になります。 これを回避するには、更新された値を保存するために、webhook で新しいタグ名を使用してください。 これは、Zabbix が提供する Jira、Jira Service Desk、Mattermost、Opsgenie、OTRS、Redmine、ServiceNow、Slack、Zammad、Zendesk の webhook と、イベントメニューエントリを含める オプションを利用するほとんどの webhook に適用されます。 ただし、同じ webhook は、同一アクション内の複数の操作またはエスカレーションステップで使用できるほか、異なる条件により同じ障害イベントではトリガーされない別のアクションでも使用できます。
  • 内部イベント用のアクションで webhook を使用する場合は、アクション操作設定で カスタムメッセージ チェックボックスをオンにし、カスタムメッセージを定義してください。 そうしないと、通知は送信されません。