第18章 Webhook の使用
Webhook は、Web ページまたは Web アプリケーションが他のアプリケーションにリアルタイムで情報を提供するための方法です。Webhook は、イベントが発生した後にのみトリガーされます。リクエストには通常、イベントの詳細が含まれています。イベントは、ホストがプロビジョニングされたことを確認する電子メールの送信などの呼出しをトリガーします。Webhook を使用すると、fire-and-forget メッセージ交換パターンを使用して、Satellite 内部イベントに基づいて外部 API への呼び出しを定義できます。リクエストを送信するアプリケーションは、レスポンスを待たないか、無視します。
Webhook のペイロードは、Webhook テンプレートから作成されます。Webhook テンプレートは、プロビジョニングテンプレートと同じ ERB 構文を使用します。使用可能な変数:
-
@event_name: イベントの名前。 -
@webhook_id: 一意のイベント ID。 -
@payload: ペイロードデータ。イベントタイプごとに異なります。個々のフィールドにアクセスするには、@payload[:key_name]Ruby ハッシュ構文を使用します。 -
@payload[:object]: データベースアクション (作成、更新、削除) によってトリガーされるイベントのデータベースオブジェクト。カスタムイベントには使用できません。 -
@payload[:context]: リクエストやセッションの UUID、リモート IP アドレス、ユーザー、組織、ロケーションなどのハッシュなどの追加情報。
Webhook は HTTP を使用するため、既存の Web サービスに新しいインフラストラクチャーを追加する必要はありません。
Satellite での Webhook の一般的な使用例は、ホストが作成または削除されたときにモニタリングシステムを呼び出すことです。
Webhook は、外部システムで実行するアクションを API を介して実行できる場合に役立ちます。追加のコマンドを実行したりファイルを編集したりする必要がある場合は、Capsules 用の shellhooks プラグインを利用できます。shellhooks プラグインを使用すると、API を介して実行できる Capsule 上のシェルスクリプトを定義できます。
shellhooks プラグインをインストールしなくても、webhook を正常に使用できます。
利用可能なイベントのリストについては、利用可能な Webhook イベント を参照してください。
18.1. Webhook への移行
従来の foreman_hooks プラグインは、webhooks プラグインが意図的に提供していないモデルオブジェクトへのフルアクセスを提供していました。
利用可能な範囲はセーフモードによって制限され、すべてのオブジェクトとマクロは両方とも API の安定性の約束の対象であり、完全に文書化されています。
webhook によってトリガーされるイベントの数は、foreman_hooks の場合よりも大幅に少なくなります。
Webhook は非同期で処理されるため、システムの内部が改ざんされるリスクは最小限に抑えられます。個々の Webhook スクリプトごとにペイロードを作成せずに、foreman_hooks から移行することはできません。ただし、webhook プラグインにはいくつかのサンプルペイロードテンプレートが付属しています。シェルフックでサンプルペイロードを使用して、移行を簡素化することもできます。
同様の結果を得るには、スクリプトテンプレートとペイロードテンプレートの両方をカスタマイズする必要があります。
