Webhooks dans la section « Avatars vidéo » : notification à votre serveur lorsque la vidéo est prête

Webhooks dans la section "Avatars vidéo" est un moyen de savoir que la vidéo est prête, sans actualiser manuellement la page : dès que la vidéo est terminée, une requête POST est envoyée à l'adresse de votre serveur, et votre serveur lui-même décide quoi faire ensuite - écrire le lien vers la base de données, envoyer le fichier au client ou passer à l'étape suivante. Cet onglet est nécessaire à ceux qui réalisent des vidéos par lots ou intègrent la génération d'avatars dans leur produit : au lieu de vérifications interminables « prêt ou pas encore », une courte notification arrive exactement au bon moment.

Pourquoi est-ce même nécessaire ?

Le rendu d'une vidéo n'est pas une opération instantanée, et il ne sert à rien de l'attendre dans un onglet ouvert. Selon les mesures de la plateforme du 07/09/2026, une vidéo Kling 3.0 de cinq secondes en 1080p est considérée comme une moyenne de 115 secondes, et dans 95 % des cas elle rentre dans 165. Pour Sora 2, la même tâche prend en moyenne environ 145 secondes. Si vous vérifiez l'état toutes les quelques secondes, des dizaines de requêtes vides apparaissent dans une seule vidéo ; Le webhook n'apparaît qu'une seule fois, lorsque le résultat apparaît réellement.

Le volume parle aussi de lui-même. Selon le journal de génération de la plateforme, sur 30 jours (du 3 septembre au 2 octobre 2026), 3 292 tâches vidéo ont démarré, dont 2 369 se sont terminées avec succès. Les vidéos sont comptées en arrière-plan et se terminent à des moments différents - cela ne peut pas être suivi manuellement et un gestionnaire de notifications soigné résout le problème lui-même.

A quoi sert l'onglet « Webhooks » ?

Il s'agit avant tout d'envoyer des notifications, sans magie. Vous enregistrez une adresse, choisissez les événements auxquels vous abonner et recevez un secret d'abonnement. La liste des points de terminaison enregistrés est stockée ici : vous pouvez voir l'adresse, les événements sélectionnés, le statut et si le point de terminaison a un secret. Le secret peut être réédité (l'ancien cessera immédiatement de fonctionner) ou le point de terminaison peut être entièrement supprimé.

L’événement provient uniquement de vos vidéos : la vidéo de quelqu’un d’autre ne sortira pas, même si elle a été comptée au même moment. Il existe également un journal des événements livrés - il est pratique de vérifier que quelque chose a réellement atteint votre serveur.

Comment commencer – étape par étape

1. Section ouverte "Avatars vidéo" et panneau webhook à l'adresse directe /ru/avatars?tab=webhooks.
2. Connectez-vous à votre compte : le paramètre n'est pas disponible pour les invités ; lorsque vous cliquez dessus, une fenêtre de connexion s'ouvrira.
3. Dans le champ « Endpoint Address », saisissez l'adresse HTTPS publique de votre serveur, par exemple https://example.com/avatar-webhook. HTTP ne fonctionnera pas : la livraison et la signature sont conçues pour un canal sécurisé.
4. Marquez les événements requis. Si vous ne sélectionnez rien, vous serez abonné à tous les événements en même temps.
5. Cliquez sur « Ajouter un point de terminaison ». Immédiatement après la création, le secret d'abonnement apparaîtra - copiez-le et enregistrez-le pour vous-même : il ne s'affichera plus.
6. Si vous n'avez pas encore votre propre serveur, cliquez sur « Remplacer notre récepteur » - les notifications seront alors accumulées dans le journal des événements livrés directement dans l'onglet.

Comment s'assurer que la demande vient de nous et qu'il ne s'agit pas d'un faux

Chaque demande est accompagnée d'un en-tête de signature - il s'agit de HMAC-SHA256, calculé à partir du corps brut de la demande comme votre secret. De votre côté, comptez la même signature et comparez : si elle ne correspond pas, nous rejetons la demande. Notre récepteur fait exactement cela et répond par 401 à une signature incorrecte. Gardez le secret sur le serveur, dans les variables d'environnement, et non dans le code client.

Ce qui vient dans la demande

Le corps est en JSON simple avec le type d'événement et les données d'entité. Par exemple, pour une vidéo terminée, il s'agit de l'événement BLK0 contenant l'identifiant de la vidéo. La liste complète des types d'événements disponibles est affichée dans l'onglet : vous pouvez la trier et ne laisser que ce dont votre service a réellement besoin.

Combien ça coûte

L'enregistrement du point de terminaison, la réédition du secret, la suppression et le journal des événements n'effacent pas les jetons : il s'agit d'un paramètre de notification et non d'une génération. Les jetons sont dépensés uniquement pour la vidéo elle-même : le prix en jetons est visible avant le lancement, et si la tâche échoue, ce qui a été radié est restitué. Il n'y a pas d'abonnement : les nouveaux utilisateurs reçoivent des jetons de départ pour leurs premiers tests.

Avec quoi combiner

• "Tâches par lots" — lancer des dizaines de vidéos avec une seule tâche ; Un webhook éliminera le besoin d’un contrôle manuel de l’état de préparation.
• "Médiathèque" — stockage des codes sources et des fichiers finis.
• "Traduction vidéo" Et "Découpe de clips" - les prochaines étapes après la génération.

Questions fréquemment posées

Quelle adresse convient pour un webhook ?

HTTPS public uniquement. Les adresses locales et HTTP ne sont pas acceptées : la notification doit passer par un canal sécurisé, et votre serveur doit être accessible de l'extérieur.

Est-il possible de recevoir des notifications s'il n'y a pas de serveur ?

Oui. Cliquez sur « Remplacer notre récepteur » - les événements seront accumulés dans le journal « Événements livrés » dans l'onglet, ils pourront être consultés sans votre backend.

Que faire si la signature ne correspond pas ?

Vérifiez que vous lisez HMAC-SHA256 à partir du corps brut de la requête (et non à partir du JSON analysé) et que vous utilisez le secret actuel : après la réémission, l'ancien cesse immédiatement de fonctionner.

Est-ce payant ?

La configuration des webhooks n’annule pas les jetons. Les jetons sont dépensés uniquement pour la génération de vidéos - leur prix est visible avant le lancement ; Il n'y a pas d'abonnement, les nouveaux utilisateurs reçoivent des jetons de départ.