# Webhook di trascrizione firmati, quando il lavoro termina

> Con un webhook di trascrizione ricevi un POST firmato quando il lavoro è pronto o non riesce. Imposta webhook_url ed evita il polling.

Canonical: https://transcript1.com/it/features/webhook-trascrizione
Language: it
Last updated: 2026-10-19

Usa un webhook di trascrizione per ricevere un POST firmato quando il testo è pronto o l’elaborazione non riesce. Aggiungi webhook_url alla creazione del lavoro: il tuo backend riceve l’evento, senza controllare lo stato a intervalli.

- Eventi transcription.completed e transcription.failed
- Firma HMAC-SHA256 a ogni invio
- Fino a 6 tentativi con attese crescenti

## Ricevi la notifica, poi recupera il testo

### Sai se la trascrizione è pronta o non è riuscita

Ricevi transcription.completed oppure transcription.failed. Se annulli una trascrizione, non inviamo webhook.

### Verifica chi ha inviato la request

X-Transcript1-Signature contiene timestamp e firma HMAC-SHA256 del corpo originale. La chiave è il segreto whsec_ del tuo team.

### Gli invii non riusciti vengono ripetuti

Una risposta 2xx conferma la ricezione. Negli altri casi riproviamo dopo 2, 4, 8, 16 e 32 minuti, per un totale di 6 tentativi.

### Serve un indirizzo HTTPS pubblico

Controlliamo l’URL quando crei il lavoro e a ogni invio. Deve usare HTTPS e risolversi in un indirizzo pubblico.

### La notifica non contiene il testo completo

Ricevi l’oggetto della trascrizione senza il testo. Usa il suo ID per recuperare la trascrizione nel formato che ti serve.

## 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](https://transcript1.com/it/docs/webhooks#set-a-webhook-url) 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.

### Caricamento con notifica al termine

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Gestisci 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](https://transcript1.com/it/docs/api-reference#get-a-transcription) 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.

### POST inviato al tuo URL

```
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](https://transcript1.com/it/docs/webhooks#verify-the-signature) 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.

### Node.js

```
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));
```

- [Esempi completi di verifica della firma](https://transcript1.com/it/docs/webhooks)

## 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](https://transcript1.com/it/docs/api-reference#get-a-transcription). 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.

## Domande frequenti

### Dove trovo il segreto per verificare la firma?

Nella pagina “Webhooks” della dashboard. Inizia con whsec_ e appartiene al team. Puoi ruotarlo da quella pagina quando vuoi.

### Cosa succede se il mio server non risponde?

Riproviamo con attese crescenti, fino a 6 tentativi in circa un’ora. Ogni tentativo ha un timeout di 10 secondi. Non seguiamo i redirect.

### Posso usare i webhook anche tramite MCP?

No, sono disponibili solo nell’API REST. I tool MCP attendono la trascrizione oppure restituiscono un ID da leggere in seguito.

## Approfondisci

- [Ricevere e verificare i webhook (documentazione)](https://transcript1.com/it/docs/webhooks)
- [API per file audio e video](https://transcript1.com/it/features/speech-to-text-api)
- [Agenti IA e LLM](https://transcript1.com/it/use-cases/trascrizioni-per-agenti-ia)