Recevoir les notifications de projet

Créer une destination

Après ouverture, ajoutez un récepteur HTTPS public dans Paramètres → Intégrations, choisissez les événements et conservez le secret affiché une seule fois. Vous pouvez aussi utiliser une clé avec webhooks:manage :

curl --fail-with-body https://api.captionbolt.com/v1/webhooks \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/captionbolt","events":["project.completed","project.failed"]}'

Remplacez l’URL par votre récepteur. Seul HTTPS public sur le port 443 est accepté, sans redirections. Localhost et les réseaux privés ne reçoivent pas directement les livraisons.

Choisir les événements

project.completed : export terminé ; sélectionné par défaut.
project.failed : échec du traitement ou de l’export ; sélectionné par défaut.
project.ready : traitement complet, prêt à vérifier ou exporter.
project.cancelled : projet annulé.

Les abonnements couvrent les vidéos éligibles de votre compte créées dans l’application, par REST ou MCP. Les Transcripts indépendants, projets supprimés ou hors délai d’accès sont exclus. Ready ne confirme pas une vérification humaine.

{
  "id": "event-uuid",
  "type": "project.completed",
  "createdAt": "2026-09-10T12:00:00.000Z",
  "data": {
    "projectId": "project-uuid",
    "status": "completed",
    "stage": "export",
    "resultUrl": "https://api.captionbolt.com/v1/projects/project-uuid/result"
  }
}

data.resultUrl est un endpoint authentifié, pas le fichier vidéo. Utilisez votre API Key de lecture pour obtenir de nouveaux liens. Les événements contiennent des métadonnées, pas la vidéo ni les sous-titres.

Vérifier avant de traiter

Le format suit Standard Webhooks. Utilisez un vérificateur compatible ou appliquez ces contrôles :

Gardez le corps brut et lisez webhook-id, webhook-timestamp et webhook-signature.
Retirez whsec_, décodez le secret en base64 et calculez HMAC-SHA256 sur id.timestamp.rawBody. Comparez la signature base64 en temps constant.
Rejetez les dates passées ou futures hors d’une tolérance limitée, par exemple cinq minutes. Pendant la rotation, plusieurs signatures v1, séparées par des espaces peuvent apparaître ; acceptez celle qui correspond à une clé fiable.
Dédupliquez par ID d’événement et persistez le travail avant de répondre 2xx. Traitez ensuite de façon asynchrone et accusez réception avant le délai de 15 secondes.

Le secret de signature est distinct de l’API Key. La rotation révèle le nouveau secret une fois et laisse 24 heures de chevauchement. Une nouvelle rotation est bloquée pendant ce délai.

Tester et reprendre les livraisons

Le test dans les paramètres envoie webhook.test : traitez-le séparément. Consultez l’historique des 30 derniers jours, corrigez le récepteur et relancez manuellement une livraison échouée ou déjà remise.

Les événements peuvent se répéter et arriver dans le désordre. Une réponse non 2xx, une erreur réseau ou l’absence d’accusé donne trois tentatives automatiques au total : la première, puis deux relances après environ une et cinq minutes. Le troisième échec arrête l’envoi automatique. Une relance manuelle conserve l’ID et rétablit trois tentatives ; le récepteur doit être idempotent.

Désactiver arrête les livraisons en attente ; une requête en cours peut se terminer. Supprimer la destination efface son historique. Supprimer le projet ou laisser son accès expirer arrête ses notifications en attente. Les Webhooks ne prolongent pas l’accès média : sauvegardez à temps ou consultez l’état du projet.