> This page is for プラットフォーム, version V4 (default).
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 Experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - レガシー: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# V4 Webhook

## Webhook とは

**Webhook** は、（新しいファイルでトランスコードが完了したとき、コメントが追加されたとき、プロジェクトが作成されたときなど）アカウントで**何か興味深いことが発生するとすぐに** Frame.io が起動する、プッシュスタイルの HTTP コールバックです。
API をポーリングする代わりに、パブリック HTTPS URL を指定します。Frame.io は、その URL に JSON ペイロードをリアルタイムで送信するので、次のことができます。

#### メタデータを外部 DAM／MAM に同期

#### Slack チャンネルまたはチケットシステムに入力

Webhook の詳細と機能について詳しくは、[https://docs.webhook.site/](https://docs.webhook.site/) を参照してください。

## エンドポイントの概要

| **操作**                        | **エンドポイント**                                                           | **詳細**                             |
| ----------------------------- | --------------------------------------------------------------------- | ---------------------------------- |
| Webhook の**作成**               | POST /v4/accounts/\{account\_id}/workspaces/\{workspace\_id}/webhooks | `name`、`url`、`events[]` を含んだ本文     |
| ワークスペースのすべての webhook を**リスト** | GET /v4/accounts/\{account\_id}/workspaces/\{workspace\_id}/webhooks  | ページネーションをサポートします                   |
| 1 つの webhook の**表示**          | GET /v4/webhooks/\{webhook\_id}                                       | 作成時にのみ署名シークレットを返します                |
| Webhook の**更新**               | PATCH /v4/webhooks/\{webhook\_id}                                     | `url`、`events` または `is_active` の変更 |
| Webhook の**削除**               | DELETE /v4/webhooks/\{webhook\_id}                                    | 配信をすぐに停止します                        |

> **Warning**
>
> **認証** — すべての V4 エンドポイントには、Adobe Developer Console を通じて取得された OAuth 2.0 アクセストークンが必要です。従来の開発者トークンおよび JWT は**受け付けられません**。

## Frame V4 の変更と更新

> **Info**
>
> レガシーで作成された webhook は、次の変更で V4 に転送されます。
>
> 1. **ペイロード構造**：アカウント ID をペイロードに追加しました
> 2. **エンドポイントの変更**：`team_id` は、JSON ペイロードでは提供されなくなりましたが、代わりに 次の URL のパスパラメーターにあります：`https://api.frame.io/v4/accounts/:account_id/workspaces/:workspace_id/webhooks`
> 3. **API 統合**：API 構造、エンドポイント、および認証方法の変更により、リソースの強化および検索のために Frame.io API への後続の呼び出しを行う、受信 webhook の既存のコードは、更新が必要です
> 4. **イベントタイプ**：アセット webhook は、個別のファイルおよびフォルダーイベントに分割されました。アセットイベントを含むレガシーからの webhook は、適切なファイルおよびフォルダーイベントを持つように更新する必要があります

> **Warning**
>
> **移行後の webhook ステータス** — アカウントが Frame.io V4 に移行されると、以前のバージョンの既存の webhook は自動的に無効になります。これにより、再アクティベートする前に webhook エンドポイントおよび統合ロジックを変更して、V4 のアップデートで作業できるようになります。V4 の互換性を得るように更新されていない webhook は、適切な変更をせずに有効にされた場合、エラーが発生します。どの webhook が非アクティブかを確認するには、API を通じて `is_active` フィールドを確認するか、[webhook 設定](https://next.frame.io/settings/webhooks)を確認してから、オンに戻します。

## Webhook イベントサブスクリプション

Webhook を作成および更新する場合は、関心のあるイベントを特定します。必要な数だけ選択します。イベント数を減らし、webhook を異なる命名スキームおよび異なるエンドポイントで論理的に分割すると、受信側でビジネスロジックをモデル化して、共有された機能でのフィルタリングおよびルーティングを減らすことができます。

> **Note**
>
> イベントスコープ：すべてのイベントのスコープは、webhook の作成中に提供されるワークスペースに限定されます。つまり、そのワークスペース内のすべてのプロジェクトで実行されたアクションのイベントが送信されます。

### プロジェクト

| イベント              | 説明                    |
| ----------------- | --------------------- |
| `project.created` | 新しいプロジェクトが**作成**されました |
| `project.updated` | プロジェクトの設定が**更新**されました |
| `project.deleted` | プロジェクトが**削除**されました    |

### ファイル

| イベント                    | 説明                                                                                                                                  |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `file.created`          | Frame.io にファイルが**作成**されました。\*注意：\*これは、ファイルのアップロードが完了する前にトリガーされます。ハンドラーが完全なファイルを必要とする場合、代わりに `upload.completed` イベントをリッスンすることをお勧めします |
| `file.ready`            | ファイルがアップロードおよび処理された後、すべてのトランスコードが**完了**しました                                                                                         |
| `file.updated`          | ファイルの名前、または他の情報が変更されました                                                                                                             |
| `file.deleted`          | （手動またはその他の方法で）ファイルが**削除**されました                                                                                                      |
| `file.upload.completed` | ファイルが**アップロード**されました                                                                                                                |
| `file.versioned`        | ファイルバージョンが**作成**されました                                                                                                               |

### フォルダー

| イベント             | 説明                   |
| ---------------- | -------------------- |
| `folder.created` | 新しいフォルダーが**作成**されました |
| `folder.updated` | フォルダーの設定が**更新**されました |
| `folder.deleted` | フォルダーが**削除**されました    |

### コメント

| イベント                  | 説明                       |
| --------------------- | ------------------------ |
| `comment.created`     | 新しいコメントまたは返信が**作成**されました |
| `comment.updated`     | コメントが更新されました             |
| `comment.deleted`     | コメントが**削除**されました         |
| `comment.completed`   | コメントが**完了**としてマークされました   |
| `comment.uncompleted` | コメントが**未完了**としてマークされました  |

### メタデータ

| イベント                     | 説明                      |
| ------------------------ | ----------------------- |
| `metadata.value.updated` | アセットのメタデータフィールドが更新されました |

### コレクション

| イベント                 | 説明                    |
| -------------------- | --------------------- |
| `collection.created` | 新しいコレクションが**作成**されました |
| `collection.updated` | コレクションが**更新**されました    |
| `collection.deleted` | コレクションが**削除**されました    |

### カスタムフィールド

| イベント                  | 説明                       |
| --------------------- | ------------------------ |
| `customfield.created` | 新しいカスタムフィールドが**作成**されました |
| `customfield.updated` | カスタムフィールドが**更新**されました    |
| `customfield.deleted` | カスタムフィールドが**削除**されました    |

### 共有

| イベント            | 説明                |
| --------------- | ----------------- |
| `share.created` | 新しい共有が**作成**されました |
| `share.updated` | 共有が**更新**されました    |
| `share.deleted` | 共有が**削除**されました    |
| `share.viewed`  | 共有が**表示**されました    |

## Webhook メッセージペイロード

すべての webhook ペイロードには、`type` フィールド（発生したイベントを示します）と `resource` オブジェクトが含まれています。`resource` オブジェクトには、イベントに関連する Frame.io リソースの `type` と `ID` が含まれています。

### ペイロードの例

```json
{
  "account": {
    "id": "6f70f1bd-7e89-4a7e-b4d3-7e576585a181"
  },
  "project": {
    "id": "7e46e495-4444-4555-8649-bee4d391a997"
  },
  "resource": {
    "id": "d3075547-4e64-45f0-ad12-d075660eddd2",
    "type": "file"
  },
  "type": "file.ready",
  "user": {
    "id": "56556a3f-859f-4b38-b6c6-e8625b5da8a5"
  },
  "workspace": {
    "id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
  }
}
```

上記の `file.created` イベントの例では、`resource.id` は新しく作成されたファイルの `ID` を示します。さらに、`workspace`、`project`、および `user` オブジェクトも含まれます。これらには、関連する `workspace.id`、`project.id` および `user.id` が含まれています。これらの値を使用して、受信イベントをフィルタリングしたり、キャッシュされたデータをローカルで検索したりすることで、API 呼び出しを減らすことができます。

> **Warning**
>
> **アドビは、サブスクライブされたリソースに関するリソース ID 以外の追加情報は含めません**。
>
> アプリケーションで追加情報やコンテキストが必要な場合は、API 呼び出しを行って、参照されているリソースに関する詳細情報を検索することをお勧めします。

## セキュリティ

デフォルトでは、すべての webhook に署名キーがあります。この設定できない署名シークレットを使用して、リクエストが Frame.io から発生していることを確認できます。

設定した webhook のレスポンスペイロードには、この webhook に固有の署名シークレットが含まれます。このシークレットは、**この初期 webhook 作成応答でのみ提供される**ので、シークレットストレージまたは環境変数の安全な場所に保存してください。  後で使用して、webhook がアドビのサーバーから直接読み取られ、傍受や操作が一切行われていないことを確認してください。

### Webhook 署名の確認

中間者攻撃や反射攻撃から統合を保護するには、wbhook ペイロードの署名を確認することが不可欠です。確認により、Webhook ペイロードが実際に Frame.io によって送信され、トランスポートでペイロードコンテンツが変更されていないことが確認されます。

`POST` リクエストには、次の HTTP ヘッダーも含まれます。

| ヘッダー名                               | 説明                   | 例                                                                     |
| ----------------------------------- | -------------------- | --------------------------------------------------------------------- |
| `X-Frameio-Request-Timestamp`       | リクエストが送信されたタイムスタンプ   | `1604004499`                                                          |
| `X-Frameio-Signature`               | 計算 webhook 署名        | `v0=a77ce6856e609c884575c2fd211d07a9ad1c3f72e19c06ff710e8f086ffca883` |
| `user-agent: "Frame.io V4 API"`     | v4 のヘッダーのユーザーエージェント  |                                                                       |
| `user-agent: "Frame.io Legacy API"` | レガシーのヘッダーのユーザーエージェント |                                                                       |

**`Python`**

```python title="Python"
import hmac
import hashlib

def verify_signature(curr_time, req_time, signature, body, secret):
    """
    Verify Webhook signature
    :Args:
        curr_time (float): Current epoch time
        req_time (float): Request epoch time
        signature (str): Signature provided by the Frame.io API for the given request
        body (str): Webhook body from the received POST
        secret (str): The secret for this Webhook that you saved when you first created it
    """
    if int(curr_time) - int(req_time) < 500:
        message = 'v0:{}:{}'.format(req_time, body)
        calculated_signature = 'v0={}'.format(hmac.new(
            bytes(secret, 'latin-1'),
            msg=bytes(message, 'latin-1'),
            digestmod=hashlib.sha256).hexdigest())
        if calculated_signature == signature:
            return True
    return False
```

**タイムスタンプ**は、送信 webhook が送信されたときの、Frame.io のシステムからのシステム時間です。これは、[リプレイ](https://en.wikipedia.org/wiki/Replay_attack)攻撃を防ぐために使用できます。この時刻が現地時間から 5 分以内であることを確認することをお勧めします。

**署名**は、Webhook が最初に作成されたときに提供された署名キーを使用する HMAC SHA256 ハッシュです。

**署名を確認するには、次の手順に従います。**

#### 署名の抽出

HTTP ヘッダーから署名を抽出します。

#### 署名するメッセージの作成

次のようにバージョン、配信時刻、およびリクエスト本文を組み合わせることで、署名するメッセージを作成します：`v0:timestamp:body`

#### HMAC SHA256 の計算

署名シークレットを使用して、HMAC SHA256 署名を計算します。

#### 署名の比較

計算された署名を指定されたものと比較してください。

> **Note**
>
> 指定された署名には、接頭辞 `v0=` が付きます。現在、Frame.io で署名リクエスト用に用意されているのはこれだけです。この接頭辞が計算された署名の先頭に追加されていることを確認してください。

## 再試行とログ記録

#### 再試行ポリシー

* 合計 5 回の試行（最初 + 4 回の再試行）
* 15 秒から開始される指数バックオフ（+ジッタ）
* `2xx` 以外のステータスまたは 5 秒を超えるタイムアウトにより、再試行がトリガーされます

#### 障害ログ記録

Frame.io は、次を含んだ**障害ログ**を保持します：`webhook_id`, `account_id`, `event_type`, `resource_id`, `user_id`

## Webhook チュートリアル

### 手順 1：受信側の設定（URL を把握するために最初に実施します）

ここでは、[webhook.site](http://webhook.site/) を使用しています。これにより、ペイロードの確認に使用できる、単回使用の webhook 受信者を簡単に作成し、実際のビジネスロジックなしで基本的な応答を送信できます。初めて [https://webhook.site](https://webhook.site/) に移動すると、すぐにコピーして使用できる一意の webhook エンドポイントが作成されます。

この URL は、セッション固有です。

![手順 1 の例](/_fern-files/frame-io.docs.buildwithfern.com/09ca9e64de4cd7b5b0982e6c2ae5f0978320cd11272b448b7f9f8c2aff1239ab/docs/pages/v4/guides/webhook_site_example.gif)

### 手順 2：サブスクライブするイベントの選択

このチュートリアルでは、シンプルにし、`file.created` イベントをサブスクライブするだけのためにこの webhook を設定します。Webhook 作成に使用する JSON ペイロードは、次のとおりです。

```json
{
    "data": {
        "name": "asset.created sample webhook",
        "events": ["file.created"],
        "url": "https://webhook.site/c05f2216-9558-4816-bc09-f77ee7b9de40"
    }
}
```

### 手順 3：  Postman を使用して webhook リソースを作成

Postman を使用して、webhook リソースを作成する API 呼び出しを行い、ペイロードで [webhook.site](http://webhook.site/) エンドポイントを提供します。

### 手順 4：テスト

Webhook サブスクリプションを作成し、webhook を受信するようにエンドポイントを設定したら、起動する原因となる適切なアクションを実行して最初の webhook をトリガーし、テストしてみましょう。

アドビのサンプルは `file.created` トリガーでトリガーするように設定されているので、先に進み、webhook が設定された対応するアカウントおよびワークスペース内の任意のプロジェクトに新しいアセットをアップロードしましょう。

![手順 4 の例](/_fern-files/frame-io.docs.buildwithfern.com/7503b906ce873425c6477487378fe9c513d5cbddc524754f0e1fe8ba10de5c16/docs/pages/v4/guides/trigger_asset_created_webhook.gif)

## その他のリソース

#### [Ngrok](https://ngrok.com/)

**Ngrok**は、一般にアクセス可能な URL で公開する必要がある webhook を操作する開発者にとって素晴らしいツールです。ローカル環境からインターネットへの安全なトンネルを作成し、ローカルサーバーを公開して webhook ペイロードをリアルタイムで受信できるようにします。

#### [Hookdeck](https://hookdeck.com/)

**Hookdeck**は、堅牢なイベントゲートウェイを提供することで、チームが webhook を確実に管理できるように設計されたプラットフォームです。Webhook 処理を一元化してイベントを見逃さないようにし、失敗した webhook のフィルタリング、キュー追加、再試行などの機能を提供します。

#### [Webhook.site](https://webhook.site)

**Webhook.site** は、webhook のプロトタイプ作成およびテストのための高品質なツールであり、一意の自動生成された URL に送信された HTTP リクエストをキャプチャおよび確認するためのシンプルでありながら強力なプラットフォームを提供します。

#### [Val.town](https://www.val.town/)

**Val.town**は、小さな JavaScript および Python 関数をブラウザーから直接、記述、テスト、および展開するプロセスを簡素化するので、webhook ハンドラーを素早くプロトタイプ作成するための卓越したツールです。