Webhooks

Configurer les webhooks

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

Tout code de 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 considérées comme des échecs. Par défaut, Transloadit effectue 5 nouvelles tentatives en cas d’échec, avec un facteur exponentiel de 1,97.

L’accusé de réception confirme la réception, pas la réussite du traitement. Examinez 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 n’importe quelle combinaison de ces filtres pris en charge :

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

Les renvois de notifications réutilisent les filtres fournis dans la requête initiale de création de l’Assembly. Les filtres définis uniquement dans un Template ne sont pas conservés lors du renvoi ; un renvoi peut donc inclure des données omises de la notification initiale. Fournissez notification_payload dans la requête initiale de création de l’Assembly 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 assurer 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 sérialisation exacte de l’Assembly Status JSON, et le champ signature contient son HMAC en notation hexadécimale minuscule.

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 les octets exacts de la chaîne transloadit, à l’aide de l’Auth Secret de confiance sélectionné comme décrit ci-dessous.
3. Comparez l’empreinte calculée à signature en utilisant 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 via un Assembly Replay. Les renvois de notifications recherchent d’abord l’Auth Key enregistrée dans l’Assembly Status sous api_auth_key_id. Si cette clé n’est pas enregistrée, ne peut pas être retrouvée, a été supprimée ou si sa recherche échoue, le renvoi de notification utilise à la place l’Auth Secret de l’appelant authentifié qui demande le renvoi.

Les Assembly Replays conservent la valeur historique api_auth_key_id du parent. Par exemple, si la clé A crée une Assembly et que la clé 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 d’Assembly et celui de renvoi de notification, et que les deux clés restent actives. Gardez les secrets applicables du parent et de la création par réexécution à la disposition de votre vérificateur ; ne supposez pas que toutes les livraisons concernant une même Assembly utilisent le même secret.

Sélectionnez les secrets de vérification dans une configuration de confiance côté serveur pour le Workspace et l’Assembly attendus, et non à partir de champs de la charge utile non vérifiée. Lorsque plusieurs secrets configurés sont applicables, acceptez la requête uniquement 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, pour assurer la rétrocompatibilité. Considérez 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 de vérification de nos SDK lorsqu’elle est disponible. 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 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)
}

Activer une signature plus forte

Définissez notification_signature_algo sur sha256 ou sha384 lors de la création ou de la mise à jour d’une Auth Key. Ce paramètre est indépendant du paramètre signature_algo de la clé, qui contrôle la signature des requêtes API. Pour les clés existantes comme pour les nouvelles, la valeur par défaut est null ; omettre ce paramètre lors d’une mise à jour conserve sa valeur, et le définir sur null désactive l’en-tête supplémentaire.

Les clés pour lesquelles cette option est activée ajoutent un en-tête Transloadit-Signature contenant sha256:<lowercase hex digest> ou sha384:<lowercase hex digest>. Le champ de formulaire historique signature reste inchangé. Les deux signatures couvrent les octets UTF-8 de la chaîne JSON filtrée exacte contenue dans le champ de formulaire décodé transloadit, avant l’encodage URL. Ne signez pas le corps HTTP encodé et n’analysez pas le JSON pour le sérialiser à nouveau avant de le vérifier.

Les notifications initiales utilisent les paramètres de la clé chargés lors de l’authentification de l’Assembly. La modification d’une clé ne modifie pas les Assemblies déjà en cours. Les renvois explicites de notifications recherchent ensemble le secret actuel de la clé enregistrée et son algorithme de notification ; les paramètres de l’appelant sont utilisés ensemble si la recherche de la clé historique recourt à la solution de repli décrite ci-dessus. Les nouvelles tentatives automatiques conservent l’algorithme sélectionné et la charge utile sérialisée pour la livraison concernée.

Déployez un vérificateur qui prend en charge le nouvel en-tête avant de l’activer. Dès que votre intégration exige la signature plus forte, rejetez tout en-tête absent ou invalide et rejetez les algorithmes autres que celui configuré dans votre vérificateur. Ne vous rabattez jamais silencieusement sur le champ SHA-1. Lors de la migration, déployez d’abord tous les émetteurs de notifications et les gestionnaires de renvoi. Laissez aux caches des paramètres des clés le temps de se rafraîchir et aux Assemblies antérieures le temps de se terminer, puis confirmez que l’en-tête est présent dans les livraisons concernant les Assemblies créées après le changement avant de l’exiger. Dès que les récepteurs exigent l’en-tête, privilégiez le passage de l’émetteur à une version ultérieure : revenir à une version qui ne prend en charge que le format historique empêche les livraisons, sauf si les récepteurs rétablissent d’abord la compatibilité avec les notifications utilisant uniquement le format historique.

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

// expectedAlgorithm and authSecret come from trusted server-side configuration.
function verifyStrongTransloaditWebhook({ authSecret, expectedAlgorithm, payload, signature }) {
  if (expectedAlgorithm !== 'sha256' && expectedAlgorithm !== 'sha384') return false
  if (typeof payload !== 'string' || typeof signature !== 'string') return false
  const prefix = `${expectedAlgorithm}:`
  if (!signature.startsWith(prefix)) return false
  const hex = signature.slice(prefix.length)
  if (!/^[0-9a-f]+$/.test(hex)) return false
  const expected = createHmac(expectedAlgorithm, authSecret).update(payload, 'utf8').digest()
  if (hex.length !== expected.length * 2) return false
  return timingSafeEqual(Buffer.from(hex, 'hex'), expected)
}

La vérification de la signature authentifie la charge utile ; elle n’empêche pas les livraisons en double. Rendez le traitement idempotent en utilisant l’identité vérifiée de l’Assembly et l’état propre à l’application.