Recevez les notifications de projets

Préparez votre récepteur

Les Webhooks envoient HTTP lorsqu’une vidéo est prête à vérifier, qu’un export termine, qu’un projet échoue ou est annulé. Disponibles avec les abonnements Max.

Il faut une URL HTTPS publique acceptant POST, uniquement sur le port 443. Localhost et les réseaux privés ne reçoivent pas directement. CaptionBolt ne suit pas les redirections ; utilisez un tunnel HTTPS public pour tester localement.

Remplacez https://receiver.example/captionbolt par votre URL.

Ajoutez un endpoint

Ouvrez Paramètres → Intégrations.
Saisissez URL HTTPS de destination et choisissez les événements.
Sélectionnez Ajouter un Webhook.
Enregistrez le secret de signature, affiché une seule fois.

Il sert à vérifier les notifications et diffère de la clé API.

Vous pouvez créer par REST. Configurez CAPTIONBOLT_API_KEY avec webhooks:manage selon le guide API :

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"]}'

La réponse fournit id et secret. Stockez le secret dans l’environnement sécurisé du récepteur.

Choisissez les événements

| Événement | Signification | | --- | --- | | project.ready | Traitement terminé ; vérification ou export possible | | project.completed | Export terminé et résultats disponibles ; sélection par défaut | | project.failed | Échec du traitement ou de l’export ; sélection par défaut | | project.cancelled | Projet annulé |

Tous les projets vidéo éligibles du compte sont concernés, créés sur le site, via REST ou MCP. Un nouvel endpoint reçoit les événements futurs, sans rejouer les changements passés. Transcripts indépendants, projets supprimés ou hors délai sont exclus.

project.ready ne signifie ni exporté ni vérifié par une personne.

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

Les événements contiennent des métadonnées, pas de vidéo ou texte de sous-titres. data.resultUrl est un endpoint REST authentifié. Utilisez une clé projects:read pour obtenir de nouveaux liens, puis téléchargez sans la clé. Voir téléchargements.

Vérifiez les requêtes reçues

CaptionBolt utilise Standard Webhooks. Vérifiez la signature sur le corps brut exact avant analyse ou traitement. En-têtes : webhook-id, webhook-timestamp, webhook-signature.

Exemple de récepteur Node.js

Ce récepteur vérifie les signatures et journalise ID et type pour tester les livraisons. L’exemple utilise Node.js 24 ; un autre langage convient aussi. Installez le vérificateur JavaScript dans votre projet récepteur :

npm install standardwebhooks
read -r -s -p 'CaptionBolt signing secret: ' CAPTIONBOLT_WEBHOOK_SECRET
export CAPTIONBOLT_WEBHOOK_SECRET
printf '\n'

Enregistrez dans receiver.mjs :

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const secret = process.env.CAPTIONBOLT_WEBHOOK_SECRET;
if (!secret) throw new Error("Set CAPTIONBOLT_WEBHOOK_SECRET.");
const verifier = new Webhook(secret);

createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/captionbolt") {
    response.writeHead(404).end();
    return;
  }
  let event;
  try {
    const chunks = [];
    let size = 0;
    for await (const chunk of request) {
      size += chunk.length;
      if (size > 65536) {
        response.writeHead(413).end();
        return;
      }
      chunks.push(chunk);
    }
    const rawBody = Buffer.concat(chunks).toString("utf8");
    event = verifier.verify(rawBody, {
      "webhook-id": request.headers["webhook-id"],
      "webhook-timestamp": request.headers["webhook-timestamp"],
      "webhook-signature": request.headers["webhook-signature"],
    });
  } catch {
    response.writeHead(400).end("Invalid webhook");
    return;
  }
  console.log("Verified event:", event.id, event.type);
  response.writeHead(204).end();
}).listen(3000, "127.0.0.1");

Lancez node receiver.mjs et exposez /captionbolt par HTTPS ou tunnel public. CaptionBolt doit atteindre l’URL HTTPS publique, pas l’adresse locale.

Le vérificateur contrôle signature et horodatage ; maintenez l’horloge exacte. Ne parsez pas et ne resérialisez pas le JSON avant vérification ; ne journalisez ni secret ni corps complet.

En production, remplacez le journal par une réception persistante : dédupliquez par id, sauvegardez événement ou tâche avant le 2xx, puis traitez de façon asynchrone. Si la sauvegarde échoue, renvoyez une erreur pour permettre le retry. L’exemple teste uniquement la réception, sans file persistante ni téléchargement.

Envoyez un test

Démarrez le récepteur avec son secret.
Dans Paramètres → Intégrations, ouvrez l’endpoint et choisissez Envoyer un test.
Consultez Historique des livraisons.
Confirmez un événement webhook.test vérifié dans les logs.

Un seul test peut être actif par endpoint. Attendez sa fin puis au moins 60 secondes avant un autre. Les retries manuels ont aussi un délai minimum ; respectez le délai retourné.

Traitez webhook.test séparément : il ne représente pas de vidéo terminée. Utilisez un événement réel futur pour tester les résultats.

En cas d’échec, vérifiez URL, secret, corps brut et réponse. Acquittez sous 15 secondes. Les réponses non 2xx, erreurs de connexion ou absence de réponse entraînent des retries.

Gérez les retries et les secrets

Les notifications peuvent se répéter ou arriver dans le désordre. Dédupliquez par ID et consultez l’état actuel si nécessaire.

Trois tentatives automatiques : initiale, environ une minute après le premier échec, puis cinq minutes après le deuxième. Ensuite, l’envoi automatique s’arrête. Corrigez le récepteur et choisissez Réessayer l’envoi ; l’ID reste identique et trois tentatives recommencent. L’historique dure 30 jours.

Choisissez Renouveler le secret, sauvegardez le nouveau secret et mettez à jour le récepteur. L’ancien reste valide 24 heures ; les deux signatures accompagnent les livraisons pendant ce délai. Une autre rotation est bloquée jusqu’à la fin.

Désactiver arrête les livraisons en attente ; une requête en cours peut terminer. Supprimer l’endpoint supprime aussi l’historique. Suppression ou expiration d’un projet arrête ses notifications en attente. Les Webhooks ne prolongent pas les 14 jours ; récupérez et sauvegardez vos résultats avant.