Webhooks V4

O que é um webhook?

Um webhook é um callback HTTP do tipo push que o Frame.io dispara assim que algo interessante acontece na sua conta (por exemplo, quando um novo arquivo termina a transcodificação, um comentário é adicionado ou um projeto é criado).

Em vez de consultar a API repetidamente, você fornece uma URL HTTPS pública; o Frame.io envia uma carga JSON para essa URL em tempo real para que você possa:

Para saber mais sobre o que é um webhook e o que ele faz, consulte https://docs.webhook.site/.

Visão geral do ponto de acesso

Alterações e atualizações no Frame V4

Assinaturas de eventos de webhook

Ao criar e atualizar webhooks, identifique quais eventos são de seu interesse. Escolha poucos ou muitos eventos, conforme necessário, mas observe que a experiência é melhor quando você assina menos eventos, separando seus webhooks de forma lógica com diferentes esquemas de nomenclatura e pontos de acesso diferentes, para que sua lógica de negócios no lado receptor faça menos filtragem e roteamento em funções compartilhadas.

Projetos

Arquivos

Pastas

Comentários

Metadados

Coleções

Campos personalizados

Compartilhamentos

Conteúdo da mensagem de webhook

Todos os conteúdos de webhook contêm um campo type, indicando o evento que ocorreu, e um objeto resource. O objeto resource contém o type e ID do recurso Frame.io relacionado ao evento.

Exemplo de conteúdo

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
}

No exemplo acima de um evento file.created, o resource.id indica o ID do arquivo recém-criado. Além disso, são incluídos os objetos workspace, project e user, que contêm os respectivos workspace.id, project.id e user.id. Esses valores podem ser usados para reduzir chamadas de API filtrando eventos recebidos ou consultando dados armazenados localmente em cache.

Segurança

Por padrão, todos os webhooks têm uma chave de assinatura. Esse segredo de assinatura não configurável pode ser usado para verificar se a solicitação se origina do Frame.io.

O conteúdo da resposta do webhook configurado inclui o segredo de assinatura específico desse webhook. Esse segredo é fornecido apenas nessa resposta inicial de criação do webhook; portanto, armazene-o em um local seguro no seu armazenamento de segredos ou em variáveis de ambiente. Use-o posteriormente para verificar se o webhook vem diretamente dos nossos servidores e não foi interceptado nem manipulado de nenhuma forma.

Verificação de assinaturas de webhook

Para proteger uma integração contra ataques man-in-the-middle e de repetição, é essencial verificar a assinatura do conteúdo do webhook. A verificação garante que os conteúdos de webhook tenham sido realmente enviados pelo Frame.io e que o conteúdo não tenha sido modificado durante o transporte.

Incluídos com a solicitação POST estão os seguintes cabeçalhos 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

O carimbo de data e hora é a hora do sistema nos sistemas do Frame.io quando o webhook de saída é enviado. Isso pode ser usado para evitar ataques de repetição. Recomendamos verificar se esse horário está dentro de 5 minutos em relação à hora local. A assinatura é um hash HMAC SHA256 usando a chave de assinatura fornecida quando o Webhook é criado pela primeira vez. Siga estas etapas para verificar a assinatura:

Novas tentativas e registro

Tutorial de webhook

Etapa 1: Configurar o lado receptor (feito primeiro para que você saiba qual será sua URL)

Aqui, usamos webhook.site, que permite criar facilmente um receptor de webhook de uso único que pode ser usado para inspecionar conteúdos e enviar respostas básicas sem nenhuma lógica de negócios real. Ao acessar https://webhook.site pela primeira vez, um ponto de acesso de webhook exclusivo é criado para você, que pode ser copiado imediatamente para uso.

Essa URL é exclusiva da sua sessão.

Etapa 2: Escolher os eventos que você deseja assinar

Neste tutorial, vamos manter tudo simples e configurar este webhook para assinar apenas eventos file.created. O conteúdo JSON que usaremos para criar o webhook será o seguinte.

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
}

Etapa 3: Criar um recurso de webhook usando o Postman

Usando o Postman, faça uma chamada de API para criar o recurso de webhook, fornecendo o ponto de acesso do webhook.site no conteúdo.

Etapa 4: Testar!

Agora que você criou a assinatura do webhook e configurou um ponto de acesso para receber webhooks, é hora de testar acionando o primeiro webhook por meio da ação apropriada que fará com que ele seja disparado.

Como nossa amostra foi configurada para acionar o gatilho file.created, vamos carregar um novo ativo em qualquer Projeto dentro da Conta e do espaço de trabalho correspondentes em que o webhook foi configurado.

Recursos adicionais