Diffusion vidéo

Webhooks dans les workflows vidéo : automatiser votre pipeline

Les webhooks pour l’automatisation vidéo : fonctionnement, payloads génériques et exemples Node.js. Précise que le tableau de bord public des créateurs dcast.tv ne propose pas de parcours générique de configuration des webhooks : appuyez-vous sur la documentation réelle des fournisseurs et sur les ressources de l’API partenaire le cas échéant.

dcast Team
10 min de lecture
Partager :
Webhooks dans les workflows vidéo : automatiser votre pipeline
On this page

Introduction aux webhooks

Les webhooks permettent à un système d’en notifier un autre lorsqu’un événement se produit, en envoyant une requête HTTP vers une URL que vous contrôlez. Au lieu que votre application interroge sans cesse une API pour demander « la vidéo est-elle prête ? », le fournisseur envoie un message à l’instant même où l’événement survient. Dans les workflows vidéo, c’est la colonne vertébrale de l’automatisation : la fin du transcodage, les événements du cycle de vie d’un live, la disponibilité d’un enregistrement et la finalisation d’un envoi peuvent tous déclencher l’étape suivante de votre pipeline, sans qu’une personne surveille un tableau de bord.

Importez, diffusez et vendez vos vidéos. Commencez avec l’offre gratuite, sans carte bancaire.

Commencer gratuitement

Le principe est simple et identique d’un fournisseur à l’autre. Le serveur récepteur valide la requête (idéalement en vérifiant une signature cryptographique), répond rapidement avec un statut 2xx et place le travail lourd dans une file pour un traitement en arrière-plan. Tout le reste (noms d’événements, forme des payloads, comportement des nouvelles tentatives) varie selon le fournisseur ; c’est pourquoi comprendre le schéma compte plus que mémoriser les champs d’un fournisseur en particulier.

Où configurer les URL de webhook

La configuration est toujours propre à chaque fournisseur. Vous enregistrez votre point de terminaison HTTPS public dans le tableau de bord ou l’API de ce fournisseur précis : le service d’encodage, la plateforme de live, le prestataire de paiement, etc. Le déroulement habituel : collez votre URL de rappel, choisissez les types d’événements à recevoir et conservez en lieu sûr le secret de signature qu’on vous remet. Il n’existe pas d’« écran des webhooks » universel valable pour tous les fournisseurs ; vous suivez la documentation du produit que vous intégrez réellement, car l’emplacement exact et la terminologie diffèrent à chaque fois.

DCAST et les produits destinés aux développeurs

L’expérience créateur publique de dcast.tv ne comprend pas de page de paramètres « Webhooks » générique où ajouter des URL quelconques pour des événements comme « transcodage terminé » ou « stream démarré ».

Les intégrations partenaires et API (la documentation et les outils destinés aux développeurs ou aux surfaces Pro/partenaires) sont l’endroit où se trouvent les rappels, les événements signés et les éléments de feuille de route associés, décrits dans la documentation officielle de l’API partenaire et pour développeurs, et non dans un parcours fictif de tableau de bord grand public. En cas de doute, fiez-vous à la documentation officielle plutôt qu’à un tutoriel, y compris celui-ci.

Événements de webhook courants dans les workflows vidéo

Les termes exacts varient selon le fournisseur, mais les catégories d’événements sont remarquablement constantes dans tout le secteur :

  • Transcodage ou encodage terminé : la ressource est prête à être lue ou à passer à l’étape suivante du pipeline (vignettes, sous-titrage, publication).
  • Stream démarré / terminé : le cycle de vie du live, utile pour l’analytique, les notifications et le déclenchement de l’enregistrement.
  • Enregistrement prêt : la version replay ou VOD d’un live est désormais disponible.
  • Envoi terminé : l’ingestion est achevée et le fichier brut est stocké en sécurité.

Un pipeline bien conçu enchaîne ces événements : upload completed lance le transcodage, transcoding finished déclenche la génération des vignettes et rend la ressource publiable, et recording ready prévient les abonnés qu’un replay existe. Chaque événement fait un travail et passe le relais au suivant.

Comprendre les payloads de webhook

Les payloads sont presque toujours au format JSON. Lisez toujours le schéma réel de votre fournisseur, car les noms de champs et l’imbrication diffèrent ; l’exemple ci-dessous est générique et purement illustratif :

{
  "event": "transcoding_finished",
  "video_id": "12345",
  "status": "success",
  "filename": "example_video.mp4",
  "timestamp": "2023-10-05T12:00:00Z"
}

Deux habitudes vous éviteront de vrais ennuis. D’abord, ne supposez jamais qu’un champ existe : vérifiez sa présence avant de l’utiliser, car les fournisseurs ajoutent et renomment des champs au fil du temps. Ensuite, considérez le payload comme une notification, pas comme la source de vérité. Pour tout ce qui est important, utilisez l’identifiant du payload pour récupérer l’enregistrement faisant foi auprès de l’API du fournisseur plutôt que de croire aveuglément le corps du webhook, car les payloads peuvent être falsifiés ou rejoués.

Gérer les webhooks avec Node.js

Mettre en place un écouteur simple

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const port = 3000;

app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  console.log('Received webhook event: ' + payload.event);
  res.status(200).send('Webhook received');
});

app.listen(port, () => {
  console.log('Webhook server listening on port ' + port);
});

Exemple : se brancher selon le type d’événement

app.post('/webhook', (req, res) => {
  const payload = req.body;
  if (payload.event === 'transcoding_finished') {
    console.log('Transcoding finished for video ' + payload.video_id);
  }
  res.status(200).send('Webhook received');
});

Vérifier les signatures

L’étape de sécurité la plus importante consiste à vérifier qu’une requête provient bien de votre fournisseur et n’a pas été falsifiée. La plupart des fournisseurs signent chaque requête avec un HMAC du corps brut de la requête, calculé avec votre secret partagé, et envoient le résultat dans un en-tête. À vous de recalculer cette signature et de la comparer en temps constant :

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  // constant-time compare avoids leaking timing information
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Notez que la vérification de signature exige généralement le corps brut de la requête, exactement tel que reçu. Si votre analyseur JSON a déjà resérialisé le corps, les octets peuvent différer et la signature ne correspondra jamais ; capturez donc le corps brut avant l’analyse lorsqu’un fournisseur l’exige.

Gestion des erreurs et nouvelles tentatives

Mettez en place l’idempotence en stockant l’identifiant de chaque événement traité et en ignorant les doublons, car les fournisseurs livreront forcément le même événement plus d’une fois lors de coupures réseau. Ne renvoyez un statut 2xx qu’après avoir accepté l’événement en toute sécurité, c’est-à-dire généralement après l’avoir écrit dans une file durable, et non après avoir terminé le travail proprement dit. Traitez ensuite les tâches longues de façon asynchrone pour que l’émetteur ne dépasse pas le délai d’attente. Si vous faites le travail lourd en ligne et mettez trop de temps à répondre, le fournisseur considère l’envoi comme un échec, réessaie, et vous finissez par traiter le même événement à répétition.

Bonnes pratiques

  1. Sécurité : utilisez toujours HTTPS, vérifiez les signatures de chaque requête et rejetez tout ce qui échoue à la validation avec un code 401 ou 403.
  2. Idempotence : partez du principe que des livraisons en double surviendront et dédoublonnez par identifiant d’événement, afin qu’une nouvelle livraison ne provoque jamais de double facturation, de double publication ni de double notification.
  3. Accusé de réception rapide : répondez vite avec un 2xx, puis faites le vrai travail dans une file d’arrière-plan.
  4. Supervision : journalisez chaque livraison et chaque échec, déclenchez une alerte en cas de pic de réponses non 2xx et conservez une file de lettres mortes (dead-letter queue) pour les événements que vous n’avez pas pu traiter.

Tester les webhooks en local

Un webhook ayant besoin d’une URL accessible publiquement, tester sur votre ordinateur portable exige un tunnel. Des outils comme ngrok exposent votre serveur local sur une adresse HTTPS publique temporaire, afin qu’un fournisseur puisse atteindre http://localhost:3000 pendant le développement. De nombreux fournisseurs proposent aussi un bouton « envoyer un événement de test » et un journal de livraison qui montre chaque tentative et le code de réponse que vous avez renvoyé ; utilisez les deux pour vérifier que votre point de terminaison valide les signatures, renvoie rapidement un 2xx et traite correctement le payload avant de vous y fier en production.

Conclusion

Les webhooks sont un moyen standard et fiable d’automatiser les pipelines vidéo, mais seulement si la plateforme que vous utilisez les propose réellement, et seulement si vous les gérez de façon sécurisée et idempotente. Vérifiez le comportement dans la documentation à jour du produit, et vérifiez les signatures de chaque requête. Construisez le schéma correctement une fois pour toutes, et la même rigueur vaudra pour chaque fournisseur que vous intégrerez.

Prochaines étapes et ressources

  • Utilisez la documentation officielle de votre fournisseur d’encodage ou de streaming pour connaître les types d’événements, le format des payloads et les détails de la vérification des signatures.
  • Pour DCAST, appuyez-vous sur les ressources publiées de l’API partenaire / pour développeurs afin de comprendre le périmètre d’intégration ; évitez de supposer qu’une interface de webhooks existe dans le tableau de bord grand public de dcast.tv.

Foire aux questions

Que sont les webhooks et comment fonctionnent-ils dans les workflows vidéo ?

Les webhooks sont des rappels HTTP qu’un fournisseur envoie vers une URL que vous contrôlez lorsqu’un événement précis se produit. Dans les workflows vidéo, ils notifient votre application en temps réel de la fin d’un transcodage, du début et de la fin d’un stream, de la finalisation d’un envoi ou de la disponibilité d’un enregistrement, ce qui vous permet de déclencher l’étape automatisée suivante sans interrogation répétée.

Comment configurer des webhooks pour un fournisseur vidéo ?

Le processus est toujours propre à chaque fournisseur. Vous enregistrez votre point de terminaison HTTPS public dans le tableau de bord ou l’API de ce fournisseur, vous sélectionnez les types d’événements qui vous intéressent et vous conservez le secret de signature qu’il vous remet. Il n’existe pas de parcours universel : suivez donc la documentation du produit exact que vous intégrez. Pour dcast.tv en particulier, appuyez-vous sur l’API partenaire officielle et sur les ressources pour développeurs plutôt que de supposer qu’un écran de webhooks existe dans le tableau de bord grand public.

Quels sont les événements typiques qui déclenchent des webhooks dans les workflows vidéo ?

Parmi les événements courants : « transcodage terminé », « stream démarré », « stream terminé », « enregistrement prêt » et « envoi terminé ». Les libellés exacts varient selon le fournisseur, mais ces catégories couvrent la plupart des besoins d’automatisation.

Comment sécuriser et vérifier les payloads de webhook ?

Servez votre point de terminaison en HTTPS et vérifiez la signature cryptographique que le fournisseur envoie avec chaque requête, à l’aide de votre secret partagé et d’une comparaison en temps constant. Considérez le payload comme une notification plutôt que comme la source de vérité : utilisez les identifiants qu’il contient pour récupérer l’enregistrement faisant foi auprès de l’API du fournisseur avant toute action aux conséquences importantes.

Comment gérer les livraisons de webhook en double ou en échec ?

Rendez votre gestionnaire idempotent en enregistrant l’identifiant de chaque événement traité et en ignorant les répétitions, puisque les fournisseurs réessaient en cas de réponse non 2xx ou de dépassement de délai. Accusez réception rapidement avec un 2xx après avoir placé l’événement en file en toute sécurité, traitez le travail lourd de façon asynchrone et conservez une file de lettres mortes ainsi qu’une supervision, afin que les livraisons en échec soient visibles et récupérables.

Documentation de l’API sur ce sujet

streaminglive streamingvidéowebhooksworkflowsautomatisation vidéo
d

dcast Team

Des experts du streaming vidéo qui aident les créateurs à réussir.

Lancez votre activité vidéo dès aujourd’hui

Importez, diffusez et vendez vos vidéos. Commencez avec l’offre gratuite, sans carte bancaire.

Commencer gratuitement