Webhook: firma HMAC, riconsegne e buone pratiche
Come ricevere il risultato delle trascrizioni via webhook: firma HMAC-SHA256, header X-VPT-Signature e X-VPT-Event, 6 tentativi di consegna con backoff.
Invece di continuare a interrogare l'API per sapere se la trascrizione è terminata, fornisci un webhook_url nella richiesta e VoxScriber invia un POST al tuo server quando il lavoro viene completato — con successo o con errore. È il modo consigliato per integrare: richiede meno chiamate e il risultato arriva subito.
Come funziona
- Invii l'audio con un
webhook_url(obbligatoriamentehttps). - Quando l'elaborazione termina, inviamo un POST a quell'URL con il risultato.
- Il tuo server risponde con uno status
2xxper confermare la ricezione.
Ogni consegna include due header di identificazione:
| Header | Contenuto |
|---|---|
X-VPT-Event | Il tipo di evento (completamento, errore, ecc.) |
X-VPT-Signature | Firma HMAC-SHA256 della consegna |
Valida sempre la firma prima di fidarti del contenuto: calcola l'HMAC-SHA256 del corpo ricevuto e confrontalo con il valore dell'header X-VPT-Signature. Una richiesta senza firma valida deve essere scartata — chiunque potrebbe scoprire l'URL del tuo endpoint.
Riconsegne automatiche
Se il tuo endpoint è irraggiungibile o troppo lento, riproviamo:
- Timeout per tentativo: 15 secondi.
- Numero massimo di tentativi: 6.
- Attesa tra i tentativi (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Tutte le consegne vengono salvate lato nostro, quindi puoi controllare lo storico con l'assistenza in caso qualcosa vada perso.
Rispondi al webhook immediatamente con 200 ed elabora il contenuto in modo asincrono (coda, job). Se la tua elaborazione richiede più di 15 secondi, la consegna viene considerata fallita e entra in coda per un nuovo tentativo — potresti ricevere lo stesso evento due volte. Gestisci gli eventi in modo idempotente.
Ricevi sempre un esito
I job bloccati non spariscono in silenzio:
- Un job in coda fermo da più di 10 minuti viene riaccodato automaticamente.
- Un job in elaborazione bloccato da più di 60 minuti viene marcato come fallito — e attiva un webhook di errore verso il tuo URL.
In pratica: per ogni audio inviato, il tuo sistema riceve un callback finale, di successo o di errore.
FAQ
Il mio server era offline. Ho perso il risultato?
Probabilmente no: ci sono fino a 6 tentativi distribuiti nell'arco di ~24 ore. Se falliscono tutti, lo storico delle consegne resta registrato — contatta l'assistenza per rielaborare.
Posso usare un URL http (senza TLS)?
No. Per sicurezza accettiamo solo URL https, senza reindirizzamenti, e gli indirizzi interni/privati sono bloccati.
Come distinguo un webhook di successo da uno di errore?
Dall'header X-VPT-Event, che identifica il tipo di evento, e dal contenuto del corpo della consegna.
Cosa deve rispondere il mio endpoint?
Qualsiasi status 2xx entro 15 secondi. Altri status (o timeout) contano come fallimento e generano un nuovo tentativo.
Articoli correlati
Non hai risolto? Apri un ticket — il nostro team risponde in fretta.