Aggiungi webhook_url quando crei il lavoro
Puoi passare webhook_url per un link video, quando apri un upload a blocchi o come campo di un caricamento multipart. Non puoi combinarlo con reuse_recent. La guida ai webhook descrive i parametri.
Un webhook è utile se l’elaborazione continua dopo la request iniziale: per registrazioni di interviste, archivi di episodi o raccolte di video social. Salva l’ID della trascrizione insieme al lavoro nella tua app, così puoi collegare la notifica all’azione giusta.
Usa l’endpoint HTTPS pubblico definitivo, senza redirect. Lo verifichiamo sia alla creazione sia all’invio; localhost non è un destinatario valido. Nell’esempio carichi un file, quindi puoi provare il flusso con una registrazione tua.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Gestisci l’evento una volta, anche se arriva di nuovo
data contiene l’oggetto della trascrizione senza il testo. Usa data.id e type per riconoscere i duplicati, poi recupera la trascrizione tramite API.
Una notifica può arrivare più di una volta: il tuo handler potrebbe elaborarla ma rispondere dopo il timeout di 10 secondi, facendo partire un altro tentativo. Salva una chiave composta da ID e tipo di evento prima di pubblicare contenuti o avvisare l’utente.
Verifica la firma, salva l’evento in modo persistente o mettilo in coda e rispondi subito con 2xx. Recupera il testo in background usando data.id. Per transcription.failed, leggi data.error e aggiorna lo stato. L’annullamento non genera callback: deve aggiornare lo stato direttamente nella tua app.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Come verificare la firma webhook HMAC-SHA256
Calcola HMAC-SHA256 sulla stringa t, un punto e il corpo originale della request, usando il segreto whsec_. Confronta le firme a tempo costante e rifiuta timestamp troppo lontani dall’ora attuale. Segui la verifica completa per validare anche l’header.
Leggi il corpo prima del parser JSON, esattamente come lo ricevi. Convertire di nuovo un oggetto in JSON può cambiare spazi o ordine dei campi e invalidare la firma. Controlla timestamp e header, confronta digest della stessa lunghezza a tempo costante e solo dopo interpreta il JSON.
Il frammento qui sotto presuppone che t e v1 siano già estratti e validati. Gli esempi completi per Node.js e Python usano una tolleranza di 5 minuti. Usa tutto il segreto, compreso il prefisso whsec_. Quando lo ruoti, la nuova chiave vale subito per gli invii successivi.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Prova anche errori, duplicati e notifiche mancanti
Prova il tuo handler con un evento completato, uno non riuscito e un duplicato. La stessa notifica non deve pubblicare due volte; una trascrizione non riuscita non deve avviare un percorso che si aspetta testo pronto. Verifica separatamente gli errori di firma e quelli della tua applicazione.
Ogni invio ha un timeout di 10 secondi. Conferma la ricezione prima di avviare indicizzazione o elaborazioni lente. Dopo la conferma, una coda persistente della tua app può ripetere quelle operazioni: i tentativi di consegna del webhook non la sostituiscono.
Se non riceviamo 2xx, oppure ci sono errori di connessione o timeout, riproviamo dopo 2, 4, 8, 16 e 32 minuti, per 6 tentativi totali. Non seguiamo i redirect. Registra ID, tipo di evento ed esito dell’invio per distinguere problemi del ricevitore ed errori di trascrizione. Non registrare mai il segreto.
Se i tentativi finiscono, controlla gli ID noti con GET della trascrizione. Salvali fin dalla creazione: il webhook non deve essere l’unica prova dell’esistenza del lavoro. Così puoi indagare su una notifica mancante senza trascrivere di nuovo il file.