Webhooks

Configurer les webhooks

Définissez notify_url dans vos Assembly Instructions, au même niveau que steps. Une fois que l’Assembly atteint un état terminal, Transloadit envoie une requête HTTP POST à cette URL.

Tout statut compris entre 200 inclus et 300 exclu accuse réception de la livraison. Les redirections et les erreurs côté client ou serveur sont traitées comme des échecs. Par défaut, Transloadit réessaie 5 fois les livraisons ayant échoué, avec un facteur exponentiel de 1,97.

L’accusé de réception confirme la réception, et non la réussite du traitement. Inspectez l’état ok ou le code error de la charge utile vérifiée pour distinguer les Assemblies terminées, annulées et en échec. Un renvoi de Notification peut également transmettre un Assembly Status non terminal ; ne supposez pas que chaque livraison signifie que le traitement est terminé.

Limiter la charge utile de la Notification

Par défaut, un webhook inclut l’Assembly Status complet. Définissez notification_payload sur un tableau contenant une combinaison quelconque de ces filtres pris en charge :

• without_params : les champs bruts d’Assembly Instructions de premier niveau params, template et merged_params sont omis.
• without_result_meta_data : meta est omis de chaque fichier dans results.
• without_results : l’objet results de premier niveau est omis.
• without_upload_meta_data : meta est omis de chaque fichier dans uploads.
• without_uploads : le tableau uploads de premier niveau est omis.

Les renvois de Notification réutilisent les filtres fournis dans la requête d’Assembly d’origine. Les filtres définis uniquement dans un Template ne sont pas conservés lors du renvoi, de sorte qu’un renvoi peut inclure des données omises de la Notification initiale. Fournissez notification_payload dans la requête d’Assembly d’origine lorsque les renvois doivent utiliser les mêmes filtres.

Le schéma de charge utile ci-dessous autorise ces omissions. Le champ meta d’un fichier téléversé peut être absent même lorsque ce fichier reste dans uploads. Les autres champs conservent leur signification dans l’Assembly Status. Acceptez les champs supplémentaires pour préserver la compatibilité, mais ne vous appuyez pas sur les champs de diagnostic non documentés.

Vérifier la signature

Les webhooks d’Assembly utilisent le type de média application/x-www-form-urlencoded. Le champ transloadit contient la chaîne sérialisée exacte de l’Assembly Status JSON, et le champ signature contient son HMAC hexadécimal en minuscules.

Pour vérifier un webhook :

1. Lisez les champs de formulaire transloadit et signature sans modifier la chaîne de la charge utile.
2. Calculez une empreinte hexadécimale HMAC-SHA1 sur la séquence exacte d’octets de la chaîne transloadit, en utilisant l’Auth Secret de confiance sélectionné comme décrit ci-dessous.
3. Comparez l’empreinte calculée à signature à l’aide d’une comparaison résistante aux attaques temporelles.
4. Analysez transloadit en tant que JSON uniquement après avoir confirmé que les signatures correspondent.

La Notification initiale d’une Assembly utilise l’Auth Secret de l’Auth Key qui a authentifié sa création, y compris lorsqu’elle a été créée par un Assembly Replay. Les renvois de Notification recherchent d’abord l’Auth Key enregistrée dans l’Assembly Status sous api_auth_key_id. Si cette Auth Key n’est pas enregistrée, ne peut pas être résolue, a été supprimée ou si sa recherche échoue, le renvoi de Notification utilise à la place l’Auth Secret de l’appelant authentifié à l’origine du renvoi.

Les Assembly Replays conservent la valeur historique de api_auth_key_id de l’Assembly parente. Par exemple, si l’Auth Key A crée une Assembly et que l’Auth Key B la réexécute, la Notification initiale de la nouvelle Assembly est signée avec le secret de B. Le renvoi de cette Notification peut utiliser le secret de A, même lorsque B appelle à la fois le point de terminaison de réexécution et celui de renvoi et que les deux Auth Keys restent actives. Gardez à la disposition de votre système de vérification les secrets applicables de l’Assembly parente et de la création par Assembly Replay ; ne supposez pas que chaque livraison pour une même Assembly utilise le même secret.

Sélectionnez les secrets de vérification à partir d’une configuration de confiance côté serveur pour le Workspace et l’Assembly attendus, et non à partir des champs de la charge utile non vérifiée. Lorsque plusieurs secrets configurés sont applicables, n’acceptez la requête que si sa signature correspond à l’un de ces secrets de confiance. Si aucun ne correspond, rejetez la requête ; ne sautez pas la vérification pour accepter un renvoi.

Contrairement aux signatures actuelles des requêtes API, le champ signature du webhook est une empreinte sha1 sans préfixe, à des fins de rétrocompatibilité. Traitez la charge utile comme non fiable et rejetez la requête si l’un des deux champs est absent, si la signature est mal formée ou si la comparaison échoue.

Utilisez l’une des fonctions utilitaires de vérification de nos SDK lorsqu’il en existe une. Si vous implémentez vous-même la vérification, ne sérialisez pas à nouveau le JSON analysé avant de calculer le HMAC : les espaces blancs et l’ordre des clés des objets font partie de la séquence d’octets signée.

import { createHmac, timingSafeEqual } from 'node:crypto'

// authSecret must come from trusted server-side configuration.
function verifyTransloaditWebhook({ authSecret, payload, signature }) {
  if (typeof payload !== 'string' || typeof signature !== 'string') return false
  if (!/^[0-9a-f]+$/.test(signature)) return false

  const expected = createHmac('sha1', authSecret).update(payload, 'utf8').digest()
  if (signature.length !== expected.length * 2) return false
  const received = Buffer.from(signature, 'hex')

  return received.length === expected.length && timingSafeEqual(received, expected)
}