V4 Webhook

Webhook とは

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

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

エンドポイントの概要

Frame V4 の変更と更新

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

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

プロジェクト

ファイル

フォルダー

コメント

メタデータ

コレクション

カスタムフィールド

共有

Webhook メッセージペイロード

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

ペイロードの例

1
{
2
  "account": {
3
    "id": "6f70f1bd-7e89-4a7e-b4d3-7e576585a181"
4
  },
5
  "project": {
6
    "id": "7e46e495-4444-4555-8649-bee4d391a997"
7
  },
8
  "resource": {
9
    "id": "d3075547-4e64-45f0-ad12-d075660eddd2",
10
    "type": "file"
11
  },
12
  "type": "file.ready",
13
  "user": {
14
    "id": "56556a3f-859f-4b38-b6c6-e8625b5da8a5"
15
  },
16
  "workspace": {
17
    "id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
18
  }
19
}

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

セキュリティ

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

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

Webhook 署名の確認

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

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

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify Webhook signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the Frame.io API for the given request
11
        body (str): Webhook body from the received POST
12
        secret (str): The secret for this Webhook that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False

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

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

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

再試行とログ記録

Webhook チュートリアル

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

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

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

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

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

1
{
2
    "data": {
3
        "name": "asset.created sample webhook",
4
        "events": ["file.created"],
5
        "url": "https://webhook.site/c05f2216-9558-4816-bc09-f77ee7b9de40"
6
    }
7
}

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

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

手順 4：テスト

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

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

その他のリソース