DocSpaceでのWebhookの使用

はじめに

Webhookを使用すると、ポータル上のイベントについて事前に設定された受信者にhttp/httpsコールバックを使用して通知することができます。ユーザーはWebhookを設定し、ポータル上のイベントが外部サービスでアクションをトリガーするようにできます。このアプローチは、特定のイベントの同期や追跡に役立ちます。

ONLYOFFICE DocSpaceのさまざまなイベントに基づいて、使用しているアプリケーションやウェブサイト側でカスタムアクションを実行するためにWebhookを使用します。

すべてのWebhookを作成および管理し、それらを設定し、各Webhookの履歴を閲覧してパフォーマンスを監査することができます。

新しいWebhookの作成

まず最初に、外部サービス内でWebhook用のエンドポイントを設定する必要があります。このエンドポイントは、DocSpaceのWebhookをリッスンし、イベント通知を受信するために使用されます。

エンドポイントを作成および設定したら、DocSpaceでWebhookを作成できます。新しいWebhookを作成するには、

開発者ツールセクションを開くには、任意のセクション（ルーム、ドキュメント）の左パネルにある開発者ツールリンクをクリックします。
デフォルトでは、ゲストを除くすべてのユーザーに開発者ツールセクションへのアクセスが有効になっているため、任意のユーザーがこのページにアクセスし、自分のWebhookを作成できます。管理者はすべての作成されたWebhookを見ることができ、ユーザーは自分のWebhookのみを見ることができます。

管理者は、左側の開発者ツールリンクを使用するか、DocSpaceの設定からこのセクションに切り替えることができます。メニューを使用して、左下の設定 -> 開発者ツールオプションを選択します。
開発者ツールで、Webhookセクションに移動します。
Webhookを作成ボタンをクリックします。
必要なパラメータを設定します：
- Webhook名 – ポータルでWebhookを便利に操作するための識別子名。
- ペイロードURL – Webhookを送信するエンドポイントのアドレス。
- シークレットキー – ペイロードURLに送信されるリクエストを検証するためのWebhookシークレットを設定します。独自のキーを入力するか、生成をクリックします。注意：シークレットキーを保存した後に再取得することはできません。シークレットキーを紛失または忘れた場合はリセットできますが、このシークレットを使用するすべての統合を更新する必要があります。
- SSL検証 – デフォルトで、このオプションはペイロードの配信時にSSL証明書を検証するために有効になっています。このパラメータを無効にすることは推奨されません。
- トリガー - すべて送信オプションを使用するか、個別のイベントラジオボタンをチェックし、特定のトリガーのみを選択します。例として、ユーザー、グループ、ドキュメント、フォルダー、ルームなどのポータルエンティティの変更に関するイベントがあります。例えば、ユーザーの作成、招待、更新、削除など。
- ターゲットID - 変更を追跡するためのユーザー、グループ、ファイル、またはフォルダーの識別子。
ペイロードURLはHEADメソッドを使用したhttpリクエストに対してステータス200で応答する必要があります。
作成ボタンをクリックします。

設定に応じて、作成されたWebhookはすべてのDocSpaceイベントまたは選択されたトリガー/複数のトリガーにのみ割り当てられます。外部サービス内でDocSpaceイベントに関する自動通知を受け取ります。特定のWebhookの作成時に選択されたトリガーは、Webhookの所有者が変更されたDocSpaceエンティティにアクセス権を持っている場合にのみトリガーされます。

Webhookの管理

作成されたWebhookは、その横にあるスイッチを使用して無効化または再有効化できます。右側のオプションアイコンアイコンを使用して、作成時に指定されたWebhookの設定を変更したり、Webhookの履歴を表示したり、Webhookを削除したりできます。

履歴を表示する際、配信日やステータス（未送信、2XX、3XX、4XX、5XX）でWebhookをフィルタリングできます。フィルターアイコンフィルターボタンをクリックし、必要なパラメータを選択して適用をクリックします。

リスト内の1つまたは複数のWebhookを選択し、上部に表示される再試行アイコン 再試行オプションを使用して選択したWebhookを再配信することができます。または、特定のWebhookの横にあるオプションアイコンアイコンをクリックし、コンテキストメニューで 再試行オプションを選択します。

特定のWebhookの横にあるオプションアイコンアイコンをクリックし、コンテキストメニューで再試行アイコン Webhookの詳細オプションを選択します。

以下の詳細が利用可能です：

ステータス – 応答ステータス。
イベントID – イベントのID。
トリガー – Webhookが起動された原因となったトリガー。
イベント時間 – イベントが発生した日付。
配信時間 – エンドポイントから応答が受信された日付。

リクエスト/レスポンスセクションでは、POSTリクエストヘッダー、POSTリクエストボディ、POSTレスポンスヘッダー、およびPOSTレスポンスボディを表示することもできます。コピーアイコンアイコンを使用してリクエストまたはレスポンスのヘッダー/ボディをクリップボードにコピーします。

Webhookの詳細キャプションの横にある再試行アイコンアイコンを使用してWebhookを再配信します。

技術的な詳細

以下の2つのサービスが使用されます：

ASC.Web.StudioはWebhookを送信するためのメソッドを提供し、WorkerServiceを起動します。
WorkerService – ブローカー（デフォルトではRabbitMQが使用されます）からメッセージを受信するためにサブスクライブし、新しいWebhookの情報を保存します。ブローカーから受信したメッセージはキューに配置され、その後キューが継続的に照会され、非同期的にASC.Webhoks.Serviceに連絡してWebhookを送信します。
ASC.Webhooks.CoreはデータベースおよびメッセージブローカーにWebhookを公開するためのメソッドと、データベースを操作するためのメソッドを提供します。

DocSpace APIの詳細については、api.onlyoffice.comを参照してください。