メインコンテンツまでスキップ

Webhook

はじめに​

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

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

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

新しいWebhookの作成​

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

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

  1. 開発者ツールセクションを開くには、任意のセクション（ファイル、ルーム、フォーム）の左パネルにある開発者ツールリンクをクリックします。

    注記

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

    管理者は、左側の開発者ツールリンクを使用するか、ワークスペースの設定からこのセクションに切り替えることができます。オプションアイコンメニューを使用して、左下の設定 -> 開発者ツールオプションを選択します。

  2. 開発者ツールで、Webhookセクションに移動します。

  3. Webhookを作成ボタンをクリックします。

  4. 必要なパラメータを設定します：

    AppsでのWebhookの使用

    • Webhook名 – ワークスペースでWebhookを便利に操作するための識別子名。

    • ペイロードURL – Webhookを送信するエンドポイントのアドレス。

    • シークレットキー – ペイロードURLに送信されるリクエストを検証するためのWebhookシークレットを設定します。独自のキーを入力するか、生成をクリックします。注意：シークレットキーは保存後に再度取得することはできません。このシークレットキーを紛失または忘れた場合は、Webhookの設定を開き、キーをリセットリンクをクリックして新しいキーを生成してください。以前のシークレットを使用しているすべての統合を更新する必要があります。

      Webhook設定

    • SSL検証 – デフォルトで、このオプションはペイロードの配信時にSSL証明書を検証するために有効になっています。このパラメータを無効にすることは推奨されません。

    • このWebhookをトリガーするイベント - すべて送信オプションを使用するか、個別のイベントラジオボタンをチェックし、特定のトリガーのみを選択します。例として、ユーザー、グループ、ファイル、フォルダー、ルーム、フォーム、AIエージェントなどのワークスペースエンティティの変更に関するイベントがあります。例えば、ユーザーの作成、招待、更新、削除など。

    • ターゲットID - 変更を追跡するためのユーザー、グループ、ファイル、またはフォルダーの識別子。

    AppsでのWebhookの使用

  5. ペイロードURLはHEADメソッドを使用したhttpリクエストに対してステータス200で応答する必要があります。

  6. 作成ボタンをクリックします。

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

Webhookの管理​

作成されたWebhookは、名前、作成者、ペイロードURL、状態とともに一覧表示されます。状態列のスイッチを使用して、Webhookを無効化または再有効化できます。右側のオプションアイコンアイコンを使用して、次のオプションを含むコンテキストメニューを開きます。

AppsでのWebhookの使用

  • 設定 - 作成時に指定されたWebhookの設定を変更します。
  • Webhook履歴 - Webhookの配信履歴を表示します。
  • Webhookを削除 - Webhookを削除します。

Webhookをクリックすると、Webhook履歴を表示できます

AppsでのWebhookの使用

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

AppsでのWebhookの使用

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

AppsでのWebhookの使用

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

AppsでのWebhookの使用

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

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

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

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

技術的な詳細​

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

  1. ASC.Web.StudioはWebhookを送信するためのメソッドを提供し、WorkerServiceを起動します。

    WorkerService – ブローカー（デフォルトではRabbitMQが使用されます）からメッセージを受信するためにサブスクライブし、新しいWebhookの情報を保存します。ブローカーから受信したメッセージはキューに配置され、その後キューが継続的に照会され、非同期的にASC.Webhoks.Serviceに連絡してWebhookを送信します。

  2. ASC.Webhooks.CoreはデータベースおよびメッセージブローカーにWebhookを公開するためのメソッドと、データベースを操作するためのメソッドを提供します。

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