Ajoutez webhook_url dès la création
Le paramètre fonctionne avec les liens vidéo, les réservations d’import en plusieurs parties et les formulaires d’import direct. Il ne peut pas être combiné avec reuse_recent. Consultez les paramètres du webhook.
Le webhook convient aux traitements en arrière-plan : transcrire un entretien importé, archiver des épisodes ou traiter une liste de vidéos. Enregistrez l’ID de la transcription avec votre tâche interne dès la création. Vous pourrez ainsi rattacher la notification à la bonne demande.
Donnez l’URL HTTPS publique définitive, sans redirection. localhost ne peut pas recevoir ces notifications. La destination est contrôlée à la création et à chaque envoi. L’exemple utilise un fichier audio pour tester tout le parcours avec un enregistrement que vous maîtrisez.
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/transcript1Traitez une seule fois chaque notification utile
data contient l’objet transcription, sans le texte. Utilisez data.id et type pour repérer les doublons, puis récupérez la transcription terminée par API.
Un même événement peut arriver plusieurs fois. Votre serveur peut l’avoir traité sans répondre avant le délai de 10 secondes. Après vérification de la signature, enregistrez durablement l’événement ou placez-le dans votre file de traitement, puis répondez rapidement en 2xx. Conservez une clé de dédoublonnage formée de l’ID et du type avant toute publication ou notification.
Récupérez ensuite le texte en arrière-plan avec data.id. Pour transcription.failed, consultez data.error et mettez à jour votre tâche. Une annulation ne déclenche pas de notification : votre propre parcours d’annulation doit mettre son état à jour.
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
}
}Vérifier la signature HMAC du webhook
Calculez le HMAC-SHA256 de t + . + le corps brut avec votre secret whsec_. Comparez les signatures en temps constant et refusez un horodatage trop éloigné de l’heure actuelle. Le guide de vérification fournit les contrôles complets.
Lisez le corps tel qu’il arrive, avant le parseur JSON. Recréer du JSON à partir d’un objet peut changer les espaces ou l’ordre des clés et invalider la signature. Validez l’en-tête et l’horodatage, comparez des signatures de même longueur, puis seulement analysez le JSON. L’extrait suppose que t et v1 ont déjà été extraits et validés.
Les exemples complets Node.js et Python appliquent une tolérance de 5 minutes. Utilisez tout le secret, préfixe whsec_ compris. Une rotation du secret de l’équipe change immédiatement la clé utilisée pour les envois suivants.
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));Testez aussi les échecs et les doublons
Testez une transcription terminée, une transcription échouée et un événement reçu deux fois. Une même fin de traitement ne doit pas publier deux fois. Un échec ne doit pas déclencher un parcours qui attend du texte. Testez séparément le refus d’une signature et les erreurs de votre traitement métier.
Répondez avant 10 secondes. N’attendez pas une indexation lente ou un appel à un modèle. Après votre réponse 2xx, une file durable dans votre application peut gérer les reprises de ces opérations ; les tentatives de livraison de transcript1 ne la remplacent pas.
Sans réponse 2xx, en cas de coupure ou de dépassement du délai, nous attendons 2, 4, 8, 16 puis 32 minutes avant de retenter. Il y a 6 tentatives au total. Les redirections ne sont pas suivies.
Journalisez l’ID, le type d’événement et l’état de la réception, jamais le secret. Si les tentatives sont épuisées, consultez les transcriptions connues par leur ID. L’événement ne doit pas être votre seule trace de leur existence : vous pourrez enquêter sans renvoyer les fichiers.