Webhooks de V4

¿Qué es un webhook?

Un webhook es una devolución de llamada HTTP de tipo push que Frame.io activa en cuanto ocurre algo relevante en la cuenta (por ejemplo, cuando termina de transcodificarse un archivo nuevo, se añade un comentario o se crea un proyecto).

En lugar de sondear la API, proporcione una URL HTTPS pública. Frame.io envía una carga útil JSON a esa URL en tiempo real para que pueda:

Para obtener más información sobre qué es un webhook y qué hace, consulte https://docs.webhook.site/.

Información general del punto final

Cambios y actualizaciones en Frame V4

Suscripciones a eventos de webhook

Al crear y actualizar webhooks, identifique qué eventos le interesan. Elija tantos como quiera, o solo unos pocos. Tenga en cuenta que la experiencia mejora si se suscribe a menos eventos y divide los webhooks de forma lógica con distintos esquemas de nomenclatura y distintos puntos finales. De este modo, podrá modelar la lógica empresarial en el punto final receptor para reducir el filtrado y el enrutamiento en funciones compartidas.

Proyectos

Archivos

Carpetas

Comentarios

Metadatos

Colecciones

Campos personalizados

Usos compartidos

Carga útil de mensajes de webhook

Todas las cargas útiles de webhook contienen un campo type, que indica el evento que se ha producido, y un objeto resource. El objeto resource contiene el tipo y el ID del recurso de Frame.io relacionado con el evento.

Ejemplo de carga útil

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
}

En el ejemplo anterior de un evento file.created, resource.id indica el ID del File recién creado. Además, se incluyen los objetos workspace, project y user, que contienen los valores relacionados workspace.id, project.id y user.id. Estos valores se pueden usar para reducir las llamadas de API mediante el filtrado de eventos entrantes o la búsqueda local de datos almacenados en caché.

Seguridad

De forma predeterminada, todos los webhooks tienen una clave de firma. Este secreto de firma no configurable se puede usar para verificar que la solicitud procede de Frame.io.

La carga útil de respuesta del webhook configurado incluye el secreto de firma específico de este webhook. Este secreto solo se proporciona en la respuesta inicial de creación del webhook, así que almacénelo en un lugar seguro, como el almacenamiento de secretos o las variables de entorno. Úselo más adelante para verificar que el webhook procede directamente de nuestros servidores y que no se ha interceptado ni manipulado de ningún modo.

Verificación de firmas de webhook

Para proteger una integración contra ataques de intermediario y de repetición, es esencial verificar la firma de la carga útil del webhook. La verificación garantiza que las cargas útiles de webhook las haya enviado realmente Frame.io y que el contenido no se haya modificado durante el transporte.

La solicitud POST incluye los siguientes encabezados 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

La marca de tiempo es la hora del sistema de Frame.io cuando se envía el webhook saliente. Puede usarse para evitar ataques de reproducción. Recomendamos verificar que esta hora esté dentro de un intervalo de 5 minutos con respecto a la hora local. La firma es un hash HMAC SHA-256 que usa la clave de firma proporcionada al crear el Webhook por primera vez. Siga estos pasos para verificar la firma:

Reintentos y registro

Tutorial de webhooks

Paso 1: Configuración del punto final receptor (se hace en primer lugar para saber cuál será la URL)

Aquí usamos webhook.site, que permite crear fácilmente un receptor de webhook de un solo uso para inspeccionar cargas útiles y enviar respuestas básicas sin ninguna lógica empresarial real. Al acceder por primera vez a https://webhook.site, se crea un punto final de webhook único que puede copiar de inmediato para usarlo.

Esta URL es exclusiva de la sesión.

Paso 2: Elección de los eventos a los que desea suscribirse

En este tutorial, mantendremos la configuración sencilla y haremos que este webhook se suscriba únicamente a eventos file.created. La carga útil JSON que usaremos para la creación del webhook será la siguiente.

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
}

Paso 3: Creación de un recurso de webhook con Postman

Use Postman para realizar una llamada de API y crear el recurso de webhook, proporcionando el punto final de webhook.site en la carga útil.

Paso 4: Prueba

Ahora que ha creado la suscripción de webhook y tiene configurado un punto final para recibir webhooks, es el momento de probarlo activando el primer webhook mediante la acción correspondiente.

Dado que el ejemplo se ha configurado para activarse con el activador file.created, cargaremos un activo nuevo en cualquier Project de la Account y el Workspace correspondientes en los que se haya configurado el webhook.

Recursos adicionales