Quand un studio grandit, les fissures d’un pipeline manuel deviennent plus bruyantes : un artiste publie un actif, un superviseur approuve un plan, une tâche passe à Terminé, mais quelque part plus tard, un autre outil attend encore d’être informé. Ces retards s’accumulent.
L’API d’événements de Kitsu change la donne en diffusant ce qui se passe en production au moment même où cela se produit. Pas de vérifications périodiques, pas de suppositions. Juste des signaux en temps réel sur lesquels vous pouvez agir.
Avec les webhooks, vous pouvez déclencher des actions automatisées dès que les données de production changent, comme lancement de rendus, synchronisation des outils de tracking, notification des équipes ou mise à jour de systèmes en aval, sans relances humaines.
Dans cet article, nous allons détailler comment les configurer et les mettre à profit, avec un exemple concret, testé en studio, que vous pouvez intégrer à un pipeline réel.
Vous pouvez trouver le code source complet de l’exemple d’intégration présenté dans ce guide sur notre GitHub :
🔗 https://github.com/cgwire/blog-tutorials/tree/main/kitsu-webhooks%20
Pourquoi les webhooks
Interroger l’API toutes les quelques minutes revient à demander des mises à jour à la production en criant à travers toute la salle : c’est lent, bruyant et facile à manquer au moment exact où quelque chose compte.
Les webhooks inversent ce modèle : au lieu de vérifier si Kitsu a changé, Kitsu informe votre pipeline immédiatement quand c’est le cas.
En pratique, cela apporte plusieurs bénéfices : un modéliseur crée une nouvelle prop dans Kitsu, et en quelques secondes, votre système de génération d’actifs met en place la structure de répertoires correcte sur le serveur, enregistre l’actif dans vos outils DCC, et le rend visible pour le layout. Personne n’a besoin de copier un nom ou de cliquer sur un bouton.
Plus tard dans le planning, une tâche d’éclairage passe à Terminé. Ce simple changement de statut peut déclencher automatiquement votre système de gestion des rendus pour envoyer le plan, en utilisant les derniers fichiers approuvés et les réglages de rendu corrects pour la production. Au moment où quelqu’un constate que la tâche est terminée, les images sont déjà en train d’être rendues.
Lorsqu’un artiste publie un fichier, le webhook peut pousser cette version directement dans votre pile de review. Le média est transcodé, téléversé et rattaché au bon plan avant que le superviseur n’ouvre sa boîte de réception. Les reviews ont lieu plus tôt, les commentaires reviennent plus vite, et le travail continue de circuler au lieu d’attendre que quelqu’un se souvienne de l’étape suivante.
C’est ce que les webhooks vous permettent d’obtenir : des données de production qui se transforment directement en action. Moins de relances, des boucles de feedback plus serrées, et un pipeline qui réagit aussi vite que vos artistes travaillent.
Événements disponibles
Kitsu émet des événements pour toutes les actions de production couvertes par les modèles de données disponibles :
- Création et mises à jour d’actifs
- Création et mises à jour de plans
- Changements de statut des tâches
- Création et publication des fichiers de preview
- Gestion des personnes
- Changements au niveau de l’organisation
- Mises à jour de plans et de séquences
Chaque événement transporte des données structurées (ID, timestamps, informations utilisateur) afin que vous puissiez identifier précisément ce qui a changé et réagir en conséquence : un journal de production en temps réel auquel vous pouvez vous abonner !
1. Créer un écouteur d’événements
La première étape consiste à enregistrer un écouteur d’événements à l’aide du client Python Kitsu (gazu). Cet écouteur agit comme un point de terminaison de webhook : il attend les événements et appelle votre fonction de rappel lorsqu’ils surviennent.
import gazugazu.set_host("http://localhost/api") gazu.set_event_host("http://localhost/api") user = gazu.log_in("admin@example.com", "mysecretpassword")
def my_callback(data): print("Asset created %s" % data"asset_id")
event_client = gazu.events.init() gazu.events.add_listener(event_client, "asset:new", my_callback) gazu.events.run_client(event_client)
Tout d’abord, on importe Gazu, le client Python officiel pour Kitsu, et on le configure pour communiquer avec un serveur Kitsu lancé localement. À la fois set_host et set_event_host pointent vers la même URL d’API : la première est utilisée pour les appels REST classiques, tandis que la seconde est spécifiquement dédiée au point d’entrée des événements (websocket). En production, il est recommandé de configurer les deux dans des threads différents, car l’écoute des événements est bloquante. Mais pour simplifier, nous faisons tout dans un seul point d’entrée dans ce tutoriel.
Ensuite, on s’authentifie en tant qu’utilisateur. Appeler gazu.log_in se connecte avec les identifiants fournis et établit une session afin que le client soit autorisé à recevoir des événements depuis Kitsu.
La fonction my_callback définit la façon dont votre pipeline réagit lorsqu’un événement est reçu. Elle prend comme entrée la charge utile de l’événement et, dans ce cas, affiche simplement l’ID de l’actif nouvellement créé. Dans un studio d’animation de taille intermédiaire, ce rappel pourrait, par exemple, déclencher un script qui crée une structure de répertoires standardisée sur le serveur de fichiers dès qu’un nouvel actif est ajouté dans Kitsu. Les artistes n’ont plus besoin de le faire manuellement, et les conventions de nommage restent cohérentes.
Après cela, le script initialise un client d’événements avec gazu.events.init(). Ce client conserve une connexion persistante avec le système d’événements de Kitsu.
L’appel à gazu.events.add_listener enregistre la fonction de rappel pour un type d’événement spécifique : "asset:new". Cela indique à Gazu : « Chaque fois que Kitsu émet un événement signalant qu’un nouvel actif a été créé, appelez my_callback avec les données de l’événement. »
Enfin, gazu.events.run_client(event_client) démarre la boucle d’événements. À partir de ce moment, le script se bloque et écoute en continu via une connexion WebSocket. Dès que quelqu’un crée un actif dans Kitsu, Kitsu émet un événement asset:new, Gazu le reçoit, et my_callback est exécuté immédiatement.
2. Envoyer des événements de test
Pour valider votre configuration, vous devez générer de vrais événements. Le moyen le plus simple consiste à effectuer des actions API standard que vous utilisez déjà en production. Par exemple, en créant un actif par programmation :
import gazugazu.set_host("http://localhost/api") user = gazu.log_in("admin@example.com", "mysecretpassword")
projects = gazu.project.all_projects() project = projects0
asset_types = gazu.asset.all_asset_types() asset_type = asset_types0
asset = gazu.asset.new_asset( project, asset_type, "My new asset", "My asset description" )
Après l’authentification, nous récupérons la liste de tous les projets visibles pour l’utilisateur connecté en appelant gazu.project.all_projects(). Dans cette liste, nous sélectionnons le premier projet. Dans un outil de production réel, vous chercheriez généralement un projet spécifique par nom ou par ID, mais cela permet de garder l’exemple simple.
Le même schéma est utilisé pour les types d’actifs. Le script interroge tous les types d’actifs disponibles, puis choisit le premier. Les types d’actifs définissent le type d’actif qui est créé (personnage, prop, environnement, etc.), et Kitsu exige qu’on en spécifie un lors de la création d’un nouvel actif.
Avec un projet et un type d’actif en main, nous créons un nouvel actif en appelant gazu.asset.new_asset. La fonction prend le projet cible, le type d’actif, un nom et une description. Lorsque cet appel réussit, Kitsu crée immédiatement l’actif dans sa base de données et renvoie l’objet de l’actif nouvellement créé.
À ce stade, l’actif existe dans Kitsu exactement comme s’il avait été créé via l’interface web. Cette action émet aussi un événement asset:new, permettant au reste de votre pipeline de réagir automatiquement.
Avant de le déployer à tout le studio, un pipeline TD peut créer des actifs dans un projet de staging afin de confirmer que l’événement déclenche bien l’automatisation en aval sans toucher aux données de production réelles.
3. Réagir aux événements avec des rappels
Les callbacks sont le moment où les événements Kitsu deviennent des actions concrètes de pipeline. Lorsqu’un rappel est exécuté, il reçoit une charge utile décrivant exactement ce qui a changé : un actif a été créé, une tâche a basculé vers un nouveau statut, ou un fichier a été publié. Cette charge utile devient votre point d’entrée pour piloter l’automatisation.
Une étape fréquente à l’intérieur d’un callback consiste à utiliser les ID présents dans les données de l’événement afin de récupérer le contexte complet depuis Kitsu. Par exemple, lorsqu’un événement de mise à jour de tâche est reçu, vous pouvez récupérer la tâche complète, le plan lié et le projet associé pour comprendre où, dans la production, ce changement s’est produit et quelles règles doivent s’appliquer.
À partir de là, les callbacks réalisent généralement des effets secondaires qui, autrement, nécessiteraient une intervention manuelle. Un événement de création d’actif pourrait, par exemple, entraîner la création d’un arbre de dossiers standardisé sur le disque. Un événement de publication de fichier peut envoyer le média dans votre système de review, y attacher des métadonnées, et le rendre visible aux superviseurs immédiatement.
L’idée clé est que les callbacks permettent à l’état de production de piloter le comportement. Au lieu de laisser des personnes réagir aux mises à jour, votre pipeline le fait, de manière cohérente et instantanée, en utilisant les mêmes règles à chaque fois.
Forkez notre dépôt Github d’exemple pour l’essayer par vous-même.
4. Rechercher des événements
Les événements en direct ne racontent qu’une partie de l’histoire. Kitsu conserve aussi un historique des événements passés, ce qui vous donne une trace fiable de ce qui s’est réellement produit en production. Quand quelque chose tourne mal, ou quand vous devez prouver qu’un traitement a fonctionné, cet historique d’événements est un outil de débogage essentiel.
Via l’API, vous pouvez interroger les événements récents et les filtrer par plage de temps ou par type d’événement. Récupérer les cent derniers événements suffit souvent à obtenir le contexte immédiat après un échec. Réduire la requête à une plage de dates précise permet d’inspecter ce qui s’est passé pendant un créneau particulier ou lors d’une exécution nocturne. Filtrer sur les événements liés aux fichiers est particulièrement utile pour suivre les problèmes de publications et d’ingestion de médias.
events = gazu.client.get("data/events/last?page_size=100")
events = gazu.client.get("data/events/last?page_size=100&before=2019-02-01")
events = gazu.client.get("data/events/last?page_size=100&before=2019-02-01&after=2019-01-01")
events = gazu.client.get("data/events/last?page_size=100&only_files=true")
En pratique, c’est ainsi que vous reconstituez une automatisation cassée. Imaginez qu’un script de publication échoue quelque part pendant la nuit, et que l’équipe du matin constate que des médias manquent dans le système de review. Au lieu de demander aux artistes quand ils ont publié ou de fouiller dans les journaux sur plusieurs machines, vous pouvez interroger Kitsu pour tous les événements de fichiers de la veille. Cela fournit une séquence exacte de publications, avec les timestamps, les utilisateurs et les entités liées.
Vous pouvez aussi suivre des événements spécifiques dans votre pipeline pour produire des rapports de productivité. Par exemple, vous pourriez compiler l’historique d’activité de votre équipe d’animation pour savoir qui a fait quoi.
Conclusion
Les événements de l’API Kitsu vous offrent une façon propre et fiable de construire des pipelines réactifs. En écoutant les changements de production plutôt que de les interroger régulièrement, vous réduisez la latence, supprimez les étapes manuelles et rendez votre studio plus résilient au fur et à mesure qu’il s’agrandit.
Bien sûr, les webhooks n’iront que jusqu’à votre maîtrise du scripting Kitsu : assurez-vous donc de consulter davantage de tutoriels techniques sur notre blog pour mieux comprendre ce que vous pouvez construire !
