V4 웹훅

웹훅이란 무엇인가요?

웹훅은 계정에서 흥미로운 이벤트가 발생하자마자(예: 새 파일 트랜스코딩 완료, 코멘트 추가, 프로젝트 생성 등) Frame.io가 즉시 실행하는 푸시 방식의 HTTP 콜백입니다.

API를 폴링하는 대신 공개 HTTPS URL을 제공하면, Frame.io가 해당 URL로 JSON 페이로드를 실시간 전송하여 다음 작업을 수행할 수 있습니다.

웹훅의 개념과 기능에 대한 자세한 내용은 https://docs.webhook.site/를 참조하세요.

엔드포인트 개요

Frame V4의 변경 및 업데이트 사항

웹훅 이벤트 구독

웹훅을 생성하고 업데이트할 때 수신할 이벤트를 지정합니다. 원하는 만큼 이벤트를 선택할 수 있지만, 더 적은 수의 이벤트를 구독하고 명명 체계와 엔드포인트가 서로 다른 웹훅으로 논리적으로 분할하는 것이 더 나은 환경을 제공합니다. 이렇게 하면 수신 측에서 비즈니스 로직을 모델링하여 공유 함수에서의 필터링 및 라우팅 작업을 줄일 수 있습니다.

프로젝트

파일

폴더

코멘트

메타데이터

컬렉션

사용자 지정 필드

공유

웹훅 메시지 페이로드

모든 웹훅 페이로드에는 발생한 이벤트를 나타내는 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 호출을 줄일 수 있습니다.

보안

기본적으로 모든 웹훅에는 서명 키가 있습니다. 변경 불가능한 이 서명 시크릿을 사용하여 요청이 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을 사용하여 웹훅 리소스 생성

Postman을 사용하여 웹훅 리소스를 생성하는 API 호출을 수행하고, 페이로드에 webhook.site 엔드포인트를 제공하세요.

4단계: 테스트!

웹훅 구독을 생성하고 웹훅을 수신할 엔드포인트 설정을 완료했으므로, 이제 첫 번째 웹훅이 실행되도록 적절한 작업을 수행하여 테스트해 볼 시간입니다!

우리의 샘플은 file.created 트리거에서 작동하도록 설정되었으므로, 해당 웹훅이 설정된 계정 및 작업 영역 내의 아무 프로젝트에나 새 에셋을 업로드하겠습니다.

추가 리소스