Webhook の基礎知識
2021/11/18 - 読み終える時間: 7 分
Webhook basics の翻訳版です。
Webhook の基礎知識
2021年11月17日
著者: Mark Zukowsky / Senior Software Architect
はじめに
VersionVault Expressは、プロジェクト内で興味深いイベントが発生した際に、通知を送信するように設定することができます。これらの通知はWebhookと呼ばれます。Webhookは単純に、HTTPでPOSTリクエストとしてエンドポイントに送られるJSONペイロードです。HTTPのPOSTリクエストに応答できるシステムであれば、Webhookのエンドポイントとなり、任意のアクションを実行できます。この記事では、webhookに関連する基本的な情報を見ていきます。webhook定義の作成と更新には、プロジェクト内でビルダーの役割を持つユーザーが必要です。ロールについては、VersionVault Expressブログの「プロジェクト・チーム・メンバーのロール」を参照してください。
プロジェクトとストリームのWebhookの比較
VersionVault Expressでは、ユーザーはプロジェクトまたはプロジェクト内の個々のストリームのいずれかのコンテキストでWebhookを作成することができます。Webhookのトリガーの実装はすべてのWebhookで同じであり、プロジェクトとストリームのWebhookの違いは、どの基本的なイベントがWebhookのトリガーを引き起こすかということです。プロジェクトWebhookの作成は、プロジェクト設定ページのWebhookページで行い、ストリームWebhookの作成は、プライマリ・ストリーム・ページのWebhookページ（ストリームごとに移動）で行います。プロジェクトとストリームのどちらのWebhookを作成する場合でも、最初のWebhookを作成することができます。
Webhook定義画面
Webhookの作成画面は、選択できるイベントを除き、プロジェクトとストリームのWebhookで同じです。
webhookの作成画面は上記の通りです。右上のアクティブ・スライダーは、Webhookがトリガーするかどうかを示しています。webhookの定義を削除せずに、webhookのトリガーを止めたい場合があります。デフォルトでは、Webhookはトリガーします。
Webhook name (Webhook名)
Webhook nameは、Webhookの識別子です。
ペイロードURL
ペイロードURLは、リクエストに応答するエンドポイントの定義です。ペイロードURLは、JSONボディを持つHTTPリクエストを受け取り、ペイロードに基づいて必要なアクションを実行します。
シークレット
シークレットは、ペイロードの内容に基づいたハッシュをWebhookのHTTPヘッダに追加します。
| イベントタイプ | トリガーの条件 |
| Join project | 招待されたユーザーが、プロジェクトへの招待を受け入れたとき、またはユーザーが初めてプロジェクトにアクセスしたとき。ユーザーの活動状況を把握するのに便利です。 |
| Create stream | ユーザーがプロジェクトに新しいストリームを作成したとき。これは、ユーザーが明示的に新しいストリームを作成したり、プロジェクトに参加した場合と、VersionVault Expressが暗黙的に新しいストリームを作成した場合の両方で発生します。 |
| Update VOB ACL | ユーザーがプロジェクトに追加または削除されたとき。 |
ストリーム Webhook 用のイベントタイプ
| イベントタイプ | トリガーの条件 |
| Deliver | ユーザーが統合ストリームに一連のアクティビティの配信を完了したとき。Webhookは統合ストリーム上で定義されます。統合ストリーム上でビルドを開始するのに適しています。 |
| Request build | ユーザーがメインストリームページで指定したストリームでのビルドを明示的に要求した場合。開発者は、配信前に開発用ストリームでビルドをテストするのに適しています。 |
| Recommend Baseline | ユーザーが指定されたストリームでベースラインを推奨したとき。ベースラインがリベースに適したものであることをユーザーに知らせるのに適しています。 |
| Make baseline | ユーザーが指定したストリームにベースラインを作成したとき。 |
| Create stream | ユーザーが親統合ストリームを基に開発ストリームを作成した場合。Webhookは親ストリームに定義されます。 |
| Rebase | ユーザーが親統合ストリームからのリベースを完了したとき。webhookは開発ストリームに定義されています。 |
Webhookのペイロード
各Webhookには、Webhookのトリガーとなったイベントに役立つさまざまな情報が含まれています。ペイロードの完全な情報については、ブログページ を参照してください。
SSL検証の無効化
デフォルトでは、サーバー証明書は利用可能な認証局に対してチェックされます。このオプションを選択すると、必要に応じて検証がバイパスされます。
Webhookの起動
Webhookが起動すると、HTTPリクエストがエンドポイントに送信されます。 ヘッダーのContent-Typeはapplication/jsonを示します。リクエストのボディはペイロードのJSON表現で、ペイロードの内容が含まれています。ペイロードのサンプルを以下に示します。すべてのWebhookのペイロードに共通するフィールドが含まれています。
Webhookの作成時にシークレットが指定されていた場合は、ペイロードとシークレットのハッシュ値を含む以下のような追加ヘッダーがHTTPリクエストに追加されます。
X-VV-Signature : sha256=866c3800b398bd8c97a575268b2dea7b6adc329a3052ffec140572ed86e61b1f
この署名は、秘密を知っているエンドポイントが再現することで、ペイロードが変更されていないことを確認できます。エンドポイントの設定方法については、VersionVault のブログサイトをご参照ください。
){kind=link}
HTTPリクエストを送信すると、sendは指定されたエンドポイントとの接続が確立するまで最大60秒、接続が確立するとエンドポイントからの応答を受信するまで最大20秒待機します。エンドポイントがリクエストに対して意味のある形で応答することが重要です。サーバーは、エンドポイントからの応答に基づいて、以下のように行動します。
-
エンドポイントが有効なレスポンスを返信した場合、ヘッダー、ボディ、レスポンスコード、レスポンステキストが取得され、Webhookの配信レコードとして保存されます。この配信記録を取得することで、Webhook配信のステータスを確認できます。
-
エンドポイントから返信がない場合や、400シリーズのHTTPコードで返信された場合は、Webhookが再試行されます。この場合、配信記録は失敗の状態で更新され、60秒後に新しいリクエストが再送されます。この再試行サイクルは3回（合計3分）繰り返されます。すべての再試行でWebhookの送信に失敗し、受理されたステータスを受信した場合、このインスタンスのWebhookのトリガーについては、それ以上の再試行は行われません。失敗した試行のステータス情報は、webhookの情報画面から取得できます。
-
決して受信しないエンドポイントが設定されている場合：Webhookのペイロードは4回送信されます。
Webhookの配信記録
各Webhookは、配信試行のステータスの記録を保持します。VersionVault ExpressのUIでこれらの記録を確認すると、エンドポイントへの到達に問題がある場合や、エンドポイントに問題がある場合、あるいはまれに成功した場合などがあります。
まとめ
Webhookは、VersionVault ExpressまたはVersionVault Explorerデスクトップ・クライアントによって開始されたかどうかに関わらず、VersionVaultで発生したさまざまなイベントに基づいてアクションを起こすための強力な方法です。ペイロードを受信して処理するエンドポイントを適切に開発すれば、統合の可能性は無限に広がります。