Cover Image

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 のブログサイトをご参照ください。

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で発生したさまざまなイベントに基づいてアクションを起こすための強力な方法です。ペイロードを受信して処理するエンドポイントを適切に開発すれば、統合の可能性は無限に広がります。

このブログについて

HCL Japan の Software 部門の複数担当者で HCL Software 全般について記しています。

Tags

Accelerate Ambassador AoC AppDev Pack AppScan ASoC beta BigFix BigFix 9.5 BigFix_Wiki branding CAA Client Applicatin Access cloud Cloud Apps Cloud Native Commerce community companion Compass compliance Connections Connections 6.5 ConnectionsDocs Connnections CVE-2021-44228 developerWorks DevOps DevOps.Launch.AppScan Digital Experience document Doino Volt Domino Domino AppDev Pacl Domino Volt DQL dW dx Enterprise Integrator event fix fix_list fixlist forum General guide HCAA HCL Ambassador HCL OneTest Embedded HCL Z and I Emulator HCL Z and I Emulator for Transformation hints_and_tips history HTMO IBM_i ID_Vault iNotes ios ios13 ipad iPhone Launch Launch.DevOps LEAP Link logo MarvelClient mobile mui nds2019 ndv12beta News Nomad Nomad Mobile Nomad Web Notes Notes/Domino Notes/Domino 10 Notes/Domino 11 notes-domino-9-10-limited-supportability-as-of-202204 Notes/Domino V12 Notes/Domion Notes/Domno notescons Now on_premises OneDB OneTest osaka press_release relay RTist SafeLinx Sametime Sametime 11 SoFy support survey system_requirement techtek Traveler Traveler 10 Traveler for Microsoft Outlook traveler.zip Unica Unica Discover Unica Interact UrbanCode Deploy UrbanCode Velocity v11 V12 Verse Verse Mobile Verse On-Premises VersionVault Volt Volt MX Webinar win7 youtube Z Z ABEND Investigator Z and I Emulator Z and I Emulator for Transformation Z and I Emulator for Web Z and I Emulator for Web Client Z Asset Optimizer ZAO ZIE ZIE for Web ZIE for Windows ZIETrans ZIEWeb うるう年 イベント ウェビナー ガイド クラウド クラウド終了 サイジング サポート サポート技術情報 サポート期間 サポート終了 セキュリティー セキュリティー脆弱性 セミナー ダイバーシティー ダウンロード テクてく テクてく Lotus 技術者夜会 ニュース ノーツコンソーシアム バージョンアップ パフォーマンス パートナー ベータ ポートフォリオ ライセンス 互換性 出荷日 各種ご案内資料 研修