Ricevi notifiche dei progetti

Prepara il ricevitore

I Webhooks inviano HTTP quando un video è pronto per revisione, un export termina, un progetto fallisce o viene annullato. Disponibili con abbonamenti Max.

Serve URL HTTPS pubblico per POST, solo porta 443. Localhost e reti private non ricevono direttamente. CaptionBolt non segue redirect; per test locali usa un tunnel HTTPS pubblico.

Sostituisci https://receiver.example/captionbolt con il tuo URL.

Aggiungi un endpoint

1. Apri Impostazioni → Integrazioni.
2. Inserisci URL HTTPS di destinazione e scegli gli eventi.
3. Seleziona Aggiungi Webhook.
4. Salva il segreto di firma, mostrato una sola volta.

Il ricevitore verifica notifiche con questo segreto, distinto dalla chiave API.

Puoi creare anche via REST. Imposta CAPTIONBOLT_API_KEY con webhooks:manage seguendo la guida 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 risposta include id e secret. Conserva il segreto nell’ambiente sicuro del ricevitore.

Scegli gli eventi

| Evento | Significato | | --- | --- | | project.ready | Elaborazione completa; revisione o esportazione possibile | | project.completed | Export terminato, risultati disponibili; selezionato per default | | project.failed | Elaborazione o export fallito; selezionato per default | | project.cancelled | Progetto annullato |

Coprono progetti video idonei dell’account, creati sul sito, REST o MCP. Un nuovo endpoint riceve eventi futuri, non modifiche passate. Esclusi Transcripts indipendenti e progetti eliminati o scaduti.

project.ready non indica video esportato o controllato da una persona.

{
  "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"
  }
}

Gli eventi contengono metadati, non file video o sottotitoli. data.resultUrl è REST autenticato. Usa chiave projects:read per link nuovi; scarica senza inviare la chiave. Vedi download.

Verifica le richieste ricevute

CaptionBolt usa Standard Webhooks. Verifica la firma sul corpo grezzo esatto prima di analizzare o agire. Header: webhook-id, webhook-timestamp, webhook-signature.

Esempio di ricevitore Node.js

Verifica firme e registra ID e tipo per testare consegne. L’esempio usa Node.js 24; sono possibili altri linguaggi. Installa il verificatore JavaScript nel tuo progetto ricevitore:

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

Salva come 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");

Esegui node receiver.mjs ed esponi /captionbolt via HTTPS o tunnel pubblico. CaptionBolt deve raggiungere URL pubblico HTTPS, non l’indirizzo locale.

Il verificatore controlla firma e timestamp; mantieni l’orologio preciso. Non analizzare e riserializzare JSON prima della verifica, né registrare segreto o corpo completo.

In produzione sostituisci i log con ricezione persistente: deduplica per id, salva evento o attività prima del 2xx e processa asincronamente. Se il salvataggio fallisce, restituisci errore per consentire retry. L’esempio verifica solo ricezione; non fornisce coda persistente o download.

Invia un test

1. Avvia ricevitore e configura segreto.
2. Apri endpoint in Impostazioni → Integrazioni, scegli Invia test.
3. Controlla Cronologia consegne.
4. Conferma webhook.test verificato nei log.

Solo un test attivo per endpoint. Attendi la fine e poi almeno 60 secondi. Anche i retry manuali hanno attesa minima; rispetta l’intervallo restituito.

Gestisci webhook.test separatamente: non rappresenta video completato. Usa un evento reale futuro per testare risultati.

Se fallisce, controlla URL, segreto, corpo grezzo e risposta. Conferma entro 15 secondi. Risposte non 2xx, errori di connessione o mancata conferma causano retry.

Gestisci retry e segreti

Le notifiche possono ripetersi o arrivare fuori ordine. Deduplica per ID e consulta lo stato attuale quando necessario.

Tre tentativi automatici: iniziale, circa un minuto dopo il primo errore, cinque minuti dopo il secondo. Poi si ferma. Correggi e scegli Riprova invio: stesso ID, altri tre tentativi. Cronologia conservata 30 giorni.

Usa Ruota segreto, salva il nuovo segreto e aggiorna il ricevitore. Il vecchio resta valido 24 ore; entrambe le firme accompagnano le consegne. Un’altra rotazione è bloccata fino alla fine.

Disattivare ferma consegne pendenti; una richiesta in corso può terminare. Eliminare cancella anche la cronologia. Eliminazione o scadenza progetto ferma notifiche pendenti. Webhooks non estendono i 14 giorni; recupera e salva risultati prima.