Webhooks : Signature HMAC, renvois et bonnes pratiques
Comment recevoir le résultat des transcriptions par webhook : signature HMAC-SHA256, en-têtes X-VPT-Signature et X-VPT-Event, 6 tentatives de renvoi avec backoff.
Au lieu d'interroger l'API pour savoir si la transcription est terminée, vous fournissez un webhook_url dans la requête et Voix2Texte envoie un POST à votre serveur lorsque le travail se termine — avec succès ou avec erreur. C'est la façon recommandée d'intégrer : moins de requêtes et le résultat arrive immédiatement.
Comment ça fonctionne
- Vous envoyez l'audio avec un
webhook_url(obligatoirementhttps). - Lorsque le traitement se termine, nous envoyons un POST à cette URL avec le résultat.
- Votre serveur répond avec un statut
2xxpour confirmer la réception.
Chaque livraison comporte deux en-têtes d'identification :
| En-tête | Contenu |
|---|---|
X-VPT-Event | Le type d'événement (achèvement, échec, etc.) |
X-VPT-Signature | Signature HMAC-SHA256 de la livraison |
Validez toujours la signature avant de faire confiance au contenu : calculez le HMAC-SHA256 du corps reçu et comparez-le avec la valeur de l'en-tête X-VPT-Signature. Toute requête sans signature valide doit être rejetée — n'importe qui peut découvrir l'URL de votre endpoint.
Renvois automatiques
Si votre endpoint est hors ligne ou trop lent, nous réessayons :
- Délai d'attente par tentative : 15 secondes.
- Nombre maximal de tentatives : 6.
- Attente entre les tentatives (backoff) : 5 min → 30 min → 2 h → 6 h → 24 h.
Toutes les livraisons sont conservées de notre côté, il est donc possible d'auditer l'historique avec le support si quelque chose se perd.
Répondez au webhook immédiatement avec 200 et traitez le contenu de manière asynchrone (file d'attente, job). Si votre traitement prend plus de 15 secondes, la livraison est considérée comme un échec et entre dans la file de renvoi — et vous pourriez finir par recevoir le même événement deux fois. Traitez les événements de manière idempotente.
Vous recevez toujours un résultat final
Les jobs bloqués ne disparaissent pas en silence :
- Un job en file d'attente bloqué depuis plus de 10 minutes est automatiquement remis en file.
- Un job en cours de traitement bloqué depuis plus de 60 minutes est marqué comme échoué — et déclenche un webhook d'erreur vers votre URL.
Autrement dit : pour chaque audio envoyé, votre système reçoit un callback final, de succès ou d'échec.
FAQ
Mon serveur est resté hors ligne. Ai-je perdu le résultat ?
Probablement pas : il y a jusqu'à 6 tentatives réparties sur environ 24 heures. Si toutes échouent, l'historique des livraisons est conservé — contactez le support pour un retraitement.
Puis-je utiliser une URL http (sans TLS) ?
Non. Par sécurité, nous n'acceptons que les URLs https, sans redirections, et les adresses internes/privées sont bloquées.
Comment distinguer un webhook de succès d'un webhook d'erreur ?
Grâce à l'en-tête X-VPT-Event, qui identifie le type d'événement, et au contenu du corps de la livraison.
Que doit répondre mon endpoint ?
N'importe quel statut 2xx dans les 15 secondes. Les autres statuts (ou timeout) comptent comme un échec et déclenchent un renvoi.
Articles connexes
Toujours pas résolu ? Ouvrez un ticket — notre équipe répond rapidement.