カスタムアプリでWorkDriveのWebhookを設定する方法

カスタムアプリでWorkDriveのWebhookを設定する方法

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

WorkDrive のカスタムアプリを使って、組織のセキュリティを強化し、生産性を向上させ、使いやすさを改善するなど、さまざまなことを実現できます。

WorkDrive チームの管理者またはスーパー管理者は、管理コンソールから直接カスタムアプリを作成・管理できるようになりました。一般的に、カスタムアプリを使用すると、WorkDrive チーム内で自分自身または組織の固有のニーズや要件を満たすアプリケーションを作成できます。

Notes
メモ: 現在、WorkDrive では Webhook を設定するためにカスタムアプリを利用します。

Info
機能の提供状況と制限事項:

この機能はWorkDrive 法人プランでのみ利用できます。
法人プランユーザーは、次の制限の範囲内でカスタムアプリを作成し、Webhook を設定できます。
  1. WorkDrive チームにつき最大 10 個までカスタムアプリを作成できます。
  2. 各カスタムアプリにつき最大 10 個まで Webhook を設定できます。
  3. 1 日あたり最大 50,000 回まで Webhook コールを実行できます。

法人プランの試用ユーザーは、次の制限の範囲内でカスタムアプリを作成し、Webhook を設定できます。
  1. WorkDrive チームにつきカスタムアプリを 1 個のみ作成できます。
  2. 各アプリにつき Webhook を 2 個までしか設定できません。
  3. 1 日あたり最大 50,000 回まで Webhook コールを実行できます。

カスタムアプリを作成するには

  1. 管理者またはスーパー管理者として WorkDrive アカウントにサインインします。
  2. 左下のAdmin Consoleをクリックします。するとAdmin Consoleウィンドウが開き、初期設定でダッシュボードタブが選択されます。

  3. 左側ペインでAppsタブをクリックして移動します。右側にAppsタブが表示されます。
  4. 右上の+ Create a new custom appをクリックします。Create new appウィンドウが開きます。

    メモ: WorkDrive チームにつき最大 10 個までカスタムアプリを作成できます。

  5. Create new appフォームに、アプリ名、説明、Client-id などの詳細を入力します。

    Client-ID を取得するには

    Client-ID は、アプリケーションを Zoho Developer Console に登録したときにのみ作成されます。Client-id がない場合、WorkDrive でカスタムアプリを作成することはできません。

    1. アプリケーションを登録するには、次の手順に従います。
    2. Zoho API Console に移動し、Get Started をクリックします。
    3. クライアント種別として Server based application を選択します。
    4. 選択したクライアント種別でアプリケーションを登録するために、必須の詳細を入力します。
      1. Client Name: Zoho に登録するアプリケーションの名前です。
      2. Homepage URL:クライアントのホームページの URL です。
      3. Authorized Redirect URIs:Zoho が認証に成功した後、付与トークンとともにリダイレクトする、アプリケーションの有効な URL です。
    5. Create をクリックして、次の認証情報を取得します。
      1. Client ID: 接続アプリによって作成されるコンシューマーキーです。
      2. Client Secret: 接続アプリによって作成されるコンシューマーシークレットです。Zoho Developer Console でのアプリケーション登録の詳細も参照してください。

  6. 作成をクリックします。作成したアプリには最大 10 個まで Webhook を設定できます。
Notesメモ:アプリ作成時に一意のシークレットキーが生成され、Webhook の認証に使用されます。

WorkDrive でカスタムアプリを表示・管理する

WorkDrive チームの管理者またはスーパー管理者は、チームに関連付けられているすべてのカスタムアプリを表示および管理できます。

Admin Consoleに移動し、Appsタブにアクセスします。Appsタブには、WorkDrive チームで作成されたすべてのカスタムアプリの一覧が表示されます。
ここから、次の操作を実行できます。
  1. アプリの詳細を更新するには: 対象のアプリをクリックします。対応するApp detailsページが開き、要件に応じてアプリ名と説明を編集できます。

  2. カスタムアプリを削除するには: WorkDrive チームからカスタムアプリを削除する場合は、削除したいアプリの App details ページ下部にあるDelete appボタンをクリックします。

Webhook

WorkDrive で Webhook を有効にすると、ファイル、フォルダー、チームフォルダー、組織単位の操作が行われた際に、指定した外部アプリ（指定した URL）にリアルタイムで通知を受け取ることができます。これにより、ファイルやフォルダーを継続的に監視する必要がなくなり、受信した情報に基づいて迅速に対応できます。
Notes
メモ:
  1. 各カスタムアプリにつき最大 10 個まで Webhook を作成できます。
  2. 1 日あたり 50,000 回までしか Webhook コールを実行できません。

Webhook を設定するには:

カスタムアプリを作成したら、Webhook を作成して設定できます。カスタムアプリに対して Webhook を設定するには、次の手順に従います。
  1. 左下のAdmin Consoleをクリックします。Admin Consoleウィンドウが開き、初期設定でダッシュボードタブが選択されます。
  2. 左側ペインでAppsタブをクリックして移動します。右側にAppsタブが表示され、すべてのカスタムアプリの一覧が表示されます。

  3. Webhook を設定したいカスタムアプリケーションを選択します。Custom appウィンドウが開き、初期設定でApp detailsタブが選択されます。

  4. Webhookタブに切り替え、Create new webhookをクリックします。Create new webhookウィンドウが開きます。
  5. Webhook 名と説明をそれぞれの項目に入力します。

  6. 通知を受信するエンドポイント URL を入力します。
    メモ: URL が有効であり、Webhook を処理できることを確認してください。

  7. トリガーイベント（File、Folder、Team Folder、Org based）を選択し、イベントの対象場所を指定します。
    WorkDrive で利用可能なイベント種別の詳細はこちらをクリックしてください

  8. Create webhookをクリックします。
    以降、WorkDrive で指定したイベントが発生するたびに、指定した URL で通知を受信します。

Webhook データの内容

Webhook データの内容とは、WorkDrive で設定したトリガーイベントが発生したときに、指定した URL に送信されるレスポンスを指します。
以下は、ファイル作成トリガーイベントに対する Webhook データの内容レスポンスの例です。
Info
{
'data': [
{
'resource_info': {
'parent_id': 'lvwg28f94012d0a484328b6175c6da296b433',
'resource_id': 'ep19987f95a0161684d8ea1b3161f16e41e38',
'resource_name': '初期設定 App Migration レポート。csv',
'base_parent_id': 'lvwg28f94012d0a484328b6175c6da296b433',
'ステータス': 1
},
'share_info': {
'役割': '7',
'shared_type': '14',
'shared_by': 5608329,
'shared_status': 14,
'shared_to': '111118000000038003'
},
'association_info': {
'entity_value': 'Guna',
'entity_label': 'データ',
'タブ': '見込み客',
'entity_id': 'EID0000001011'
},
'event_id': '839687000000338003',
'event_type': 'file_create',
'app_key': '1000。0UUMEY8E1WWRF26GF0XIHRLKDHHFNH',
'webhook_id': 'ep19987f95a0161684d8ea1b3161f16e41e38-839687000000335005',
'module_name': '',
'portal_id': '638722',
'team_id': 'lvwg26329e83825ed4815b2e685e1781d6728',
'種類': 'event_callback',
'event_time': 1600422715262,
'event_by': 61184597
}
]
}

Webhook 認証

セキュリティを強化するため、WorkDrive では Webhook 認証という方式を採用しており、各 Webhook リクエストに対して HMAC-SHA256（SHA-256 を用いたハッシュベースメッセージ認証コード）で署名を行います。これは共通鍵方式の署名メカニズムであり、WorkDrive とお客様のアプリケーションの両方が共有するシークレットキーを使用して HMAC 署名を生成および検証します。

WorkDrive が Webhook リクエストを送信する際、リクエストヘッダーの X-ZWDWebhook-署名 に HMAC 署名を含めます。お客様のアプリケーションは、リクエスト本文内の Webhook データと、リクエストヘッダー内の署名を含むこのリクエストを受信します。その後、次の手順に従います。
  1. 共有シークレットキーを使用して、Webhook データの内容に署名し、エンコードします。
  2. 生成された署名と、Webhook リクエストの X-ZWDWebhook-署名 ヘッダーに送信された値を比較します。
2 つの署名が一致する場合、そのリクエストは正当なものであり、アプリケーションと WorkDrive 間で改ざんされていないと見なされます。この仕組みにより、Webhook 通信の安全性と完全性が保証されます。

HMAC 署名の生成

HMAC 署名を作成するために、WorkDrive は JSON Web Signature（JWS）ヘッダーと Webhook データの内容を UTF-8 文字列として結合し、その結果を HMAC SHA-256 アルゴリズムでハッシュ化します。

Info
JWS ヘッダーは次のとおりです。
{
'alg': 'HS256',
'typ': 'JWT'
}

このヘッダーには次の内容が含まれます。
  1. alg: 署名ハッシュを生成するために使用されるアルゴリズム HS256。
  2. typ: 署名対象コンテンツの種類を示すために使用される typ（type）ヘッダーパラメーター。
Webhook 署名生成の手順
  1. JWT ヘッダーと Webhook データの内容をそれぞれ Base64 エンコードし、ピリオド「.」で連結します。

  2. Webhook 署名は、Base64 エンコードされたヘッダーと Webhook データの内容を SHA-256 アルゴリズムでハッシュ化し、その結果を Base64 エンコードすることで作成されます。

  3. Base64 エンコードされたヘッダー、Base64 エンコードされた Webhook データの内容、Base64 エンコードされた HMAC SHA-256 署名の 3 つの要素を、区切りとしてピリオド「.」を使用して連結します。
WorkDrive は、この署名を HTTP POST のヘッダーとして Webhook リクエストに含めます。形式は次のとおりです。
Info
X-ZWDWEBHOOK-署名: <base64 header>.<base64 本文>.<base64 HS256(<base64 header>.<base64 本文>)

HMAC 署名の検証

アプリがヘッダー内に HMAC 署名を含む Webhook リクエストを受信したら、検証処理を実行する必要があります。これは、共有シークレットキーを使用して Webhook データの内容をハッシュ化し、署名を再生成することによって行います。
Notes
メモ: 特定のカスタムアプリに設定されたすべての Webhook は、署名の検証に同じシークレットキーを使用します。

シークレットキーを取得するには:
  1. 左下の Admin Console をクリックします。Admin Console ウィンドウが開き、初期設定で ダッシュボード タブが選択されます。
  2. 左ペインから Apps タブをクリックして移動します。右側に Apps タブが表示され、すべてのカスタムアプリの一覧が表示されます。
  3. シークレットキーをコピーしたいカスタムアプリを選択します。カスタムアプリ ウィンドウが開き、初期設定で App 詳細 タブが選択されます。

    Info: すでに Webhook ページを開いている場合は、右側の シークレットキーを表示 リンクをクリックするだけでかまいません。対応する App 詳細 タブに移動します。

  4. App 詳細タブ内の シークレットキー項目 に移動し、その値をコピーします。これで、このシークレットキーを Webhook の検証に使用できます。

Webhook を検証するには:
  1. 受信した Webhook リクエストから Webhook データの内容を抽出します。

  2. 共有シークレットキーを使用して Webhook データの内容に対する HMAC 署名を計算します。この際、SHA-256 ハッシュアルゴリズムを使用します。

  3. 計算した HMAC 署名を Base64 でエンコードします。

  4. Webhook リクエストの X-ZWDWEBHOOK-署名 ヘッダーから署名を抽出します。

  5. Webhook データの内容に対して計算した Base64 エンコード済み SHA-256 ハッシュが、Webhook リクエストの X-ZWDWEBHOOK-署名 ヘッダーに含まれる値と一致することを確認します。

    一致しない場合は、その Webhook リクエストを却下します。
Notesメモ: Webhook データの正確な検証を行うため、署名の生成と検証の両方で同じエンコード方式を使用していることを必ず確認してください。

WorkDrive での Webhook の表示と管理

WorkDrive チームの管理者またはスーパー管理者は、Admin Console から各カスタムアプリの Webhook を表示および管理できます。
  1. 左下の Admin Console をクリックします。Admin Console ウィンドウが開き、初期設定で ダッシュボード タブが選択されます。

  2. 左ペインから Apps タブをクリックして移動します。右側に Apps タブが表示され、すべてのカスタムアプリの一覧が表示されます。

  3. Webhook を変更したいカスタムアプリケーションを選択します。カスタムアプリ ウィンドウが開き、初期設定で App 詳細 タブが選択されます。

  4. Webhook タブに切り替えます。ここで、そのカスタムアプリに設定されているすべての Webhook の一覧と、それぞれの管理設定にアクセスできます。

    1. Webhook を有効化または無効化するには: Webhook タブ内のオン/オフ切り替えスイッチを操作します。

    2. Webhook の名前と説明を変更するには: その他の操作アイコンをクリックし、［編集］オプションを選択します。

    3. Webhook を削除するには: その他の操作アイコンをクリックし、［削除］を選択します。確認ダイアログボックスで再度［削除］をクリックして削除を確定します。