Guide d'intégration GloopAPI
Consommation des webhooks
Vérification des signatures, répétitions et configuration des notifications.
Les notifications Webhook sont actuellement utilisées après le règlement et l'état terminal des tâches vidéo ordinaires ; n'en déduisez pas que les images synchrones, la voix ou les espaces persistants offrent les mêmes abonnements. Les notifications ne contiennent ni prompt, ni URL de résultat, ni erreur brute du service.
Configuration et abonnement
Créez un point de réception HTTPS dans Webhooks du compte et enregistrez le secret de signature affiché une seule fois. Les opérations de gestion utilisent la session connectée, pas l'API publique Bearer ; le secret est distinct de l'API Key. Lors d'une requête vidéo, fournissez un webhook_endpoint_id activé du même compte ; les URL de rappel arbitraires sont refusées. Ce champ fait partie des entrées idempotentes et ne peut pas être modifié lors d'une répétition.
Vérification de signature et déduplication
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
Les types d'événement sont video.succeeded, video.failed ou video.cancelled. Conservez les octets bruts de la requête et vérifiez Webhook-Id, Webhook-Timestamp et Webhook-Signature. La signature a la forme v1=<hex> ; HMAC-SHA256 utilise la chaîne secret comme clé. Le message concatène l'ID d'événement, l'horodatage Unix en secondes et le corps brut avec deux sauts de ligne, sans saut de ligne final :
import hashlib, hmac
message = event_id.encode() + b"\n" + timestamp.encode() + b"\n" + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(received_hex, expected)
Limitez la taille des requêtes, refusez les en-têtes manquants ou dupliqués et les versions de signature inconnues ; vérifiez la dérive d'horloge (5 minutes au maximum recommandées), analysez le JSON uniquement après validation de la signature et assurez-vous que l'id du corps correspond à Webhook-Id. L'exemple compare seulement les signatures ; le récepteur doit également effectuer tous ces contrôles.
Persistez fiablement l'événement ou terminez son traitement idempotent avant de répondre 2xx. Dédupliquez avec l'event ID stable ; lors d'une nouvelle tentative, le corps et l'ID restent identiques, mais l'horodatage et la signature changent. Après réception, interrogez la tâche et son résultat avec la Key d'origine ; la notification n'est pas un justificatif de téléchargement.
Répétitions et rotation
Les erreurs réseau, 408, 429 et 5xx déclenchent une temporisation automatique ; seuls les 2xx sont considérés comme un succès. Les redirections ne sont pas suivies, et les autres 4xx ne sont pas répétés automatiquement. La limite est de 12 tentatives sur 24 heures au maximum ; ensuite, vérifiez dans le compte et demandez explicitement un renvoi. Ce renvoi ne fait que redistribuer la notification, sans génération ni frais supplémentaires.
Modifier le point de terminaison ou renouveler la clé incrémente la version et suspend les anciennes notifications en attente ; seul un renvoi explicite utilise l'adresse et la clé actuelles. La désactivation bloque les nouvelles tentatives sans rappeler les requêtes déjà envoyées ; mettez le récepteur à jour après la rotation. Voir Tâches asynchrones et idempotence pour le rapport entre état et règlement.