Веб-перехватчики в версии V4

Что такое веб-перехватчик?

Веб-перехватчик — это обратный вызов HTTP типа push, который Frame.io отправляет сразу же, как только в вашей учетной записи ** происходит важное событие** (например, завершается перекодирование нового файла, добавляется комментарий или создается проект).

Вместо того чтобы опрашивать API-интерфейс, вы указываете публичный URL-адрес HTTPS. Frame.io в реальном времени отправляет на него полезную нагрузку JSON, что позволяет вам выполнять следующие действия.

Подробнее о том, что такое веб-перехватчик и как он работает — на сайте https://docs.webhook.site/.

Обзор конечных точек

Изменения и обновления в Frame V4

Подписки на события веб-перехватчиков

При создании и обновлении веб-перехватчиков указывайте, какие именно события вас интересуют. Можно выбрать любое количество событий. Однако обратите внимание, что система работает эффективнее, если вы подписываетесь на меньшее число событий. Логически разделяйте веб-перехватчики, используя разные схемы именования и разные конечные точки. Это позволит вам выстроить бизнес-логику на принимающей стороне так, чтобы тратить меньше ресурсов на фильтрацию и маршрутизацию данных в общих функциях.

Проекты

Файлы

Папки

Комментарии

Метаданные

Коллекции

Пользовательские поля

Общие ресурсы

Полезная нагрузка сообщения веб-перехватчика

Полезная нагрузка веб-перехватчиков всегда содержит поле type, указывающее на произошедшее событие, и объект resource. Объект resource содержит тип (type) и идентификатор (ID) ресурса Frame.io, связанного с событием.

Пример полезной нагрузки

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-интерфейса путем фильтрации входящих событий или поиска кэшированных данных на вашей стороне.

Безопасность

По умолчанию все веб-перехватчики имеют неизменяемый секретный ключ подписи, который можно использовать для проверки того, действительно ли запрос исходит от Frame.io.

Полезная нагрузка ответа для настроенного вами веб-перехватчика содержит секретный ключ подписи, уникальный для этого конкретного веб-перехватчика. Он предоставляется только в первоначальном ответе на создание веб-перехватчика, поэтому сохраните его в надежном месте — в хранилище секретных ключей или в переменных среды. Используйте его в дальнейшем для проверки того, что веб-перехватчик поступает непосредственно с наших серверов и не был перехвачен или каким-либо образом изменен.

Проверка подписей веб-перехватчиков

Чтобы защитить интеграцию от атак типа «человек посередине» и атак повторного воспроизведения, важно проверять подпись полезной нагрузки веб-перехватчика. Проверка гарантирует, что полезная нагрузка веб-перехватчика действительно была отправлена платформой 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 на момент отправки исходящего веб-перехватчика. Его можно использовать для предотвращения атак повторного воспроизведения. Мы рекомендуем проверять, чтобы это время отличалось от локального времени не более чем на 5 минут. Подпись — это хеш HMAC SHA256, использующий ключ подписи, предоставленный при первоначальном создании веб-перехватчика. Выполните следующие шаги для проверки подписи.

Повторные попытки и ведение журналов

Руководство по веб-перехватчикам

Шаг 1. Настройка принимающей стороны (выполняется в первую очередь, чтобы узнать свой URL-адрес)

В этом руководстве мы используем сервис webhook.site, который позволяет легко и быстро развернуть одноразовый приемник веб-перехватчиков. Его можно использовать для проверки полезной нагрузки и отправки базовых ответов без какой-либо реальной бизнес-логики. При первом переходе на сайт https://webhook.site для вас создается уникальная конечная точка веб-перехватчика, которую можно сразу скопировать и использовать.

Этот URL-адрес уникален для вашего сеанса.

Шаг 2. Выбор событий, на которые нужно подписаться

В этом руководстве мы не будем усложнять задачу и настроим подлписку веб-перехватчика только на события file.created. Полезная нагрузка 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

Выполните вызов API-интерфейса с помощью Postman для создания ресурса веб-перехватчика, указав в полезной нагрузке конечную точку с сайта webhook.site.

Шаг 4. Тестирование

Теперь, когда вы создали подписку веб-перехватчика и настроили конечные точки для его получения, пришло время протестировать систему. Для этого запустите первый веб-перехватчик, выполнив соответствующее действие, которое заставит его сработать.

Поскольку в нашем примере была настроена реакция на триггер file.created, мы загрузим новый ресурс в любой проект в пределах той учетной записи и рабочей среды, для которых был создан этот веб-перехватчик.

Дополнительные ресурсы