Webhookで購読するイベントを選ぶ

dosyaは1つのエンドポイントにfile.uploaded、file.deleted、share.accessedの3種類のイベントを通知できます。受信側が認証して処理できる変更だけを購読してください。イベントの選択はそのエンドポイントの以後の通知を絞り込みます。購読の保存前に発生したアクティビティは再送しません。

各イベントの意味

イベント	発生するタイミング	data内の項目
file.uploaded	新しいファイルのアップロード、または既存ファイルを置き換える新しいバージョンのアップロードが完了したとき。Webアプリ、CLI、WebDAV、SFTP、S3ゲートウェイ経由のアップロードを含みます。	file_id、name、バイト単位のsize、nullを取り得るfolder_id、数値のversion、is_new_version
file.deleted	ファイルがゴミ箱に移動されたとき、または完全に消去されたとき。フォルダーを削除すると影響を受ける子孫ファイルごとにイベントが発生します。	file_id、name、真偽値のpermanent
share.accessed	公開共有の閲覧、共有ファイルのダウンロード、共有フォルダーのアーカイブのダウンロードが行われたとき。	share_id、token、access_type、accessed_at、該当するfile_idまたはfolder_id

file.uploadedは「新規ファイル」と「新しいバージョン」の両方として扱ってください。data.is_new_versionで処理を分け、イベント名から違いを推測しないでください。削除ではpermanent: falseはゴミ箱への移動、permanent: trueは完全消去され復元できないことを意味します。共有アクセスはview、download、download_allなどのaccess_type値を使用します。閲覧ではファイル、フォルダー、バンドルを識別できます。

すべてのペイロードには最上位のイベントid、type、Unix秒のcreated時刻、workspace_id、dataもあります。リクエストヘッダーはイベントの識別情報をX-Dosya-Event-Id、選択された名前をX-Dosya-Event-Typeとして繰り返します。最上位のidを永続的な重複排除キーに使用してください。

手順

1. エンドポイントのワークスペースを有効にして連携 → Webhookを開いてください。
2. エンドポイントURLを探し、編集を選択します。
3. イベントでファイルをアップロードしました、ファイルを削除しました、共有へのアクセスを選択します。少なくとも1つを選択したままにする必要があります。そうでない場合はSelect at least one event type.が表示されます。
4. ダイアログでエンドポイントURL、説明（任意）、有効を確認し、変更を保存を選択してください。
5. エンドポイントカードに目的のイベント名がバッジとして表示されることを確認します。

Webhookの管理にはワークスペースのメンバーシップとmanage_settings権限が必要です。スコープ付きREST認証情報でエンドポイントを管理するにはフルアクセスが必要です。APIにサポートされない文字列を送るとunknown event type: VALUE、空のリストを送るとevents must be a non-empty arrayが返されます。

RESTでの対応操作はPATCH /api/webhooks/{endpoint_id}です。eventsは既存リストへの追加項目ではなく、エンドポイントの保存済み購読を表すため、置換後のリスト全体を送信してください。

curl --fail-with-body --silent --show-error --request PATCH \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID" \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{"events":["file.uploaded","file.deleted"]}'

share.created、folder.created、member.joinedは現在のAPIで受け付けるWebhookイベントの種類ではないため、使用しないでください。

実際の操作で購読を確認する

テストイベントを送信はエンドポイントが別のイベントだけを購読している場合でも、常にdata.test: trueを含む合成のfile.uploadedペイロードを送信します。URLへの到達性と署名処理の確認に使用し、その後、選択した種類ごとに無害な実操作を1回行ってください。

• 使い捨ての小さなファイルをアップロードし、is_new_version: falseを確認します。
• そのファイルの新しいバージョンをアップロードし、バージョン番号が増えたis_new_version: trueを確認します。
• テストファイルをゴミ箱に移動し、permanent: falseを確認します。完全消去はテストデータが使い捨ての場合にのみ行ってください。
• テスト用の共有を開いてからダウンロードし、受信側がviewとdownloadを区別することを確認します。

エンドポイントカードで配信を開き、event_type、作成時刻、ステータス、イベントIDを受信側のログと照合します。受信側は生の本文を認証し、イベントIDを永続化して、永続的に受け入れた後にのみ2xxレスポンスを返す必要があります。同じイベントを2回受信しても外部操作を繰り返してはいけません。

期待される結果

エンドポイントカードには必要なイベント名だけが表示されます。制御された各製品操作は対応する署名付き配信を作成し、受信側は説明されたペイロード項目を含むイベントを1回記録します。選択されていないイベントの種類はそのエンドポイントの配信を作成しません。

関連ガイド

• Webhookエンドポイントを作成する
• Webhookの配信試行を確認する
• Webhook署名を検証する