Webhooks V4

Qu’est-ce qu’un webhook ?

Un webhook est un rappel HTTP de type push que Frame.io déclenche dès qu’un événement important se produit sur votre compte (par exemple, la fin du transcodage d’un nouveau fichier, l’ajout d’un commentaire ou la création d’un projet).

Au lieu d’interroger l’API, vous fournissez une URL HTTPS publique ; Frame.io envoie alors en temps réel une payload au format JSON à cette URL, ce qui vous permet de :

Pour en savoir plus sur ce qu’est un webhook et à quoi il sert, consultez la page https://docs.webhook.site/.

Vue d’ensemble des points d’entrée

Modifications et mises à jour dans Frame V4

Abonnements aux événements de webhook

Lorsque vous créez et mettez à jour des webhooks, identifiez les événements qui vous intéressent. Choisissez-en autant que vous le souhaitez. Notez toutefois que l’expérience s’en trouve améliorée si vous vous abonnez à un nombre réduit d’événements, en répartissant vos webhooks de manière logique à l’aide de schémas de nommage distincts et de points d’entrée différents, afin de pouvoir modéliser votre logique métier côté réception et ainsi réduire le filtrage et le routage dans les fonctions partagées.

Projets

Fichiers

Dossiers

Commentaires

Métadonnées

Collections

Champs personnalisés

Partages

Payload du message du webhook

Toutes les payloads des webhooks contiennent un champ type, qui indique l’événement qui s’est produit, ainsi qu’un objet resource. L’objet resource contient le type et l’ID de la ressource Frame.io associée à l’événement.

Exemple de payload

{
  "account": {
    "id": "6f70f1bd-7e89-4a7e-b4d3-7e576585a181"
  },
  "project": {
    "id": "7e46e495-4444-4555-8649-bee4d391a997"
  },
  "resource": {
    "id": "d3075547-4e64-45f0-ad12-d075660eddd2",
    "type": "file"
  },
  "type": "file.ready",
  "user": {
    "id": "56556a3f-859f-4b38-b6c6-e8625b5da8a5"
  },
  "workspace": {
    "id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
  }
}

Dans l’exemple ci-dessus concernant l’événement file.created, resource.id indique l’ID du fichier nouvellement créé. En outre, les objets workspace, project et user sont inclus, avec les workspace.id, project.id et user.id correspondants. Ces valeurs permettent de réduire le nombre d’appels API en filtrant les événements entrants ou en consultant les données mises en cache localement.

Sécurité

Par défaut, tous les webhooks disposent d’une clé de signature. Ce secret de signature non configurable permet de vérifier que la requête provient bien de Frame.io.

La payload de la réponse pour le webhook que vous avez configuré contient le secret de signature propre à ce webhook. Ce secret n’est fourni que dans cette réponse initiale de création du webhook ; veillez donc à le conserver en lieu sûr dans votre référentiel de secrets ou dans vos variables d’environnement. Utilisez-le ultérieurement pour vérifier que le webhook provient bien directement de nos serveurs et qu’il n’a pas été intercepté ou altéré d’une quelconque manière.

Vérification des signatures des webhooks

Pour protéger une intégration contre les attaques de type « man-in-the-middle » et les attaques par rejeu, il est essentiel de vérifier la signature de la payload du webhook. La vérification permet de s’assurer que les payloads des webhooks ont bien été envoyées par Frame.io et que leur contenu n’a pas été modifié pendant le transfert.

La requête POST comprend les en-têtes HTTP suivants :

import hmac
import hashlib
def verify_signature(curr_time, req_time, signature, body, secret):
    """
    Verify Webhook signature
    :Args:
        curr_time (float): Current epoch time
        req_time (float): Request epoch time
        signature (str): Signature provided by the Frame.io API for the given request
        body (str): Webhook body from the received POST
        secret (str): The secret for this Webhook that you saved when you first created it
    """
    if int(curr_time) - int(req_time) < 500:
        message = 'v0:{}:{}'.format(req_time, body)
        calculated_signature = 'v0={}'.format(hmac.new(
            bytes(secret, 'latin-1'),
            msg=bytes(message, 'latin-1'),
            digestmod=hashlib.sha256).hexdigest())
        if calculated_signature == signature:
            return True
    return False

La date et l’heure correspondent à l’heure système des serveurs de Frame.io au moment où le webhook sortant est envoyé. Cela permet de prévenir les attaques par rejeu. Nous vous recommandons de vérifier que cette heure ne s’écarte pas de plus de 5 minutes de l’heure locale. La signature est un hachage HMAC SHA-256 généré à l’aide de la clé de signature fournie lors de la création initiale du webhook. Suivez ces étapes pour vérifier la signature :

Nouvelles tentatives et enregistrements

Tutoriel sur les webhooks

Étape 1 : configurer le serveur de réception (à effectuer en premier afin de connaître votre URL)

Ici, nous utilisons webhook.site, qui permet de créer facilement un récepteur de webhook à usage unique pouvant servir à inspecter les payloads et à envoyer des réponses simples, sans aucune logique métier. Lorsque vous accédez pour la première fois à https://webhook.site, un point d’entrée webhook unique est créé pour vous ; vous pouvez le copier immédiatement pour l’utiliser.

Cette URL est propre à votre session.

Étape 2 : choisir le ou les événements auxquels vous souhaitez vous abonner

Dans ce tutoriel, nous allons faire simple et configurer ce webhook pour qu’il se contente de s’abonner aux événements file.created. La payload JSON que nous utiliserons pour la création du webhook sera la suivante.

{
    "data": {
        "name": "asset.created sample webhook",
        "events": ["file.created"],
        "url": "https://webhook.site/c05f2216-9558-4816-bc09-f77ee7b9de40"
    }
}

Étape 3 : créer une ressource webhook à l’aide de Postman

À l’aide de Postman, effectuez un appel API pour créer la ressource webhook, en indiquant le point d’entrée webhook.site dans la payload.

Étape 4 : tester !

Maintenant que vous avez créé l’abonnement au webhook et configuré les points d’entrée pour recevoir les webhooks, il est temps de le tester en déclenchant le premier webhook en effectuant l’action appropriée qui entraînerait son déclenchement.

Comme notre exemple a été configuré pour se déclencher via l’événement file.created, nous allons maintenant charger un nouveau fichier dans n’importe quel projet du compte et de l’espace de travail dans lesquels le webhook a été configuré.

Ressources supplémentaires