Ricevere notifiche sui progetti

Creare una destinazione

Dopo l’apertura, aggiungi un ricevitore HTTPS pubblico in Impostazioni → Integrazioni, scegli eventi e conserva il segreto di firma mostrato una volta. Puoi anche usare una chiave con 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"]}'

Sostituisci l’URL con il ricevitore reale. Solo HTTPS pubblico sulla porta 443, senza reindirizzamenti. Localhost e reti private non ricevono direttamente.

Scegliere gli eventi

project.completed: esportazione finita; predefinito.
project.failed: elaborazione o esportazione fallita; predefinito.
project.ready: elaborazione completa, pronto per verifica o export.
project.cancelled: progetto annullato.

Sono inclusi i video idonei dell’account creati nell’app, con REST o MCP. Sono esclusi Transcripts indipendenti, progetti eliminati o fuori accesso. Ready non conferma una verifica umana.

{
  "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 è un endpoint autenticato, non il video. Usa la tua API Key di lettura per ottenere link aggiornati. Gli eventi contengono metadati, non video o testo dei sottotitoli.

Verificare prima di elaborare

Il formato segue Standard Webhooks. Usa un verificatore compatibile o questi controlli:

Conserva il corpo originale e leggi webhook-id, webhook-timestamp e webhook-signature.
Rimuovi whsec_, decodifica il segreto base64 e calcola HMAC-SHA256 su id.timestamp.rawBody. Confronta la firma base64 in tempo costante.
Rifiuta timestamp passati o futuri oltre una tolleranza limitata, ad esempio cinque minuti. Durante la rotazione possono esserci più firme v1, separate da spazi; accetta una corrispondenza con una chiave affidabile.
Deduplica per ID evento e persisti il lavoro prima di rispondere 2xx. Elabora in modo asincrono e conferma entro il limite di 15 secondi.

Il segreto di firma è distinto dall’API Key. La rotazione mostra il nuovo segreto una volta e consente 24 ore di sovrapposizione; altre rotazioni sono bloccate in quel periodo.

Testare e recuperare consegne

Il test nelle impostazioni invia webhook.test: gestiscilo separatamente. Consulta gli ultimi 30 giorni di storico, correggi il ricevitore e ripeti manualmente una consegna fallita o già riuscita.

Gli eventi possono ripetersi e arrivare fuori ordine. Risposte non 2xx, errori di connessione o conferme mancanti prevedono tre tentativi automatici totali: quello iniziale e altri due dopo circa uno e cinque minuti. Il terzo errore interrompe la consegna automatica. Un tentativo manuale mantiene l’ID e ripristina tutti e tre i tentativi; il ricevitore deve essere idempotente.

Disattivare ferma le consegne pendenti; una richiesta in corso può terminare. Eliminare la destinazione cancella anche lo storico. Eliminazione o scadenza del progetto ferma le sue notifiche pendenti. I Webhooks non estendono l’accesso ai media: salva in tempo o consulta lo stato del progetto.