V4 Webhook

什么是 Webhook？

Webhook 是一种推送式 HTTP 回调，当您的帐户中发生特定事件时（例如，新文件完成转码、添加了评论、创建了项目），Frame.io 会立即触发该回调。

您无需轮询 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 签名

为了保护集成免受中间人攻击和重放攻击，验证 Webhook 负载的签名至关重要。 验证可确保 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

时间戳是 Frame.io 系统发送出站 Webhook 时的系统时间。 这可以用于防止重放攻击。 我们建议验证此时间与本地时间相差是否在 5 分钟以内。 签名是使用首次创建 Webhook 时提供的签名密钥的 HMAC SHA256 哈希值。 按照以下步骤验证签名：

重试和记录

Webhook 教程

步骤 1：设置接收端（首先完成此步骤，以便您知道 URL 是什么）

在这里，我们使用 webhook.site，它允许您轻松启动一个一次性 Webhook 接收器，该接收器可用于检查负载、发送基础响应，无需任何实际的商业逻辑。 当您首次导航到 https://webhook.site 时，系统会为您创建一个独特的 Webhook 端点，您可以立即复制使用。

此 URL 是您本次会话特有的。

步骤 2：选择您要订阅的事件

在本教程中，我们将保持简单，设置此 Webhook 来仅订阅 file.created 事件。 我们用于创建 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，发出 API 调用以创建 Webhook 资源，在负载中提供 webhook.site 端点。

步骤 4：测试！

现在您已经创建了 Webhook 订阅且设置了接收 Webhook 的端点，是时候通过执行适当的操作来触发第一个 Webhook 进行测试了！

由于我们的示例已设置为在 file.created 触发器上触发，我们将继续向设置 Webhook 的相应帐户和工作区内的任何项目中上传新资产。

其他资源