# Un webhook de transcription signé, dès la fin du traitement

> Un webhook de transcription envoie un POST signé à votre webhook_url à la fin du traitement ou en cas d’échec, sans interroger l’API en boucle.

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

Un webhook de transcription prévient votre application quand le texte est prêt ou quand le traitement échoue. Ajoutez webhook_url lors de la création : transcript1 envoie un POST signé à cette adresse. Votre code attend l’événement au lieu de consulter l’API en boucle.

- transcription.completed et transcription.failed
- Signature HMAC-SHA256 sur chaque envoi
- Jusqu’à 6 tentatives, de plus en plus espacées

## Recevez l’événement, puis récupérez le texte

### Deux événements, pas un flux de progression

Vous recevez transcription.completed ou transcription.failed. Une transcription annulée ne déclenche aucun webhook.

### Une signature à vérifier à chaque réception

X-Transcript1-Signature contient un horodatage et une signature HMAC-SHA256 du corps brut, calculée avec le secret whsec_ de votre équipe.

### Des tentatives si votre serveur ne répond pas

Une réponse 2xx confirme la réception. Sinon, les nouvelles tentatives suivent des attentes de 2, 4, 8, 16 puis 32 minutes, avec 6 tentatives au total.

### Une adresse HTTPS publique

L’adresse doit utiliser HTTPS et pointer vers une IP publique. Nous la vérifions à la création de la transcription et avant chaque envoi.

### Le statut arrive, le texte se récupère ensuite

L’événement contient l’objet transcription sans son texte. Utilisez l’ID reçu pour lire la transcription dans le format dont votre application a besoin.

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

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.

### Importer un fichier avec notification de fin

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

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

### POST reçu à votre 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
  }
}
```

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

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

- [Exemples complets de vérification de signature](https://transcript1.com/fr/docs/webhooks)

## 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](https://transcript1.com/fr/docs/api-reference#get-a-transcription). L’événement ne doit pas être votre seule trace de leur existence : vous pourrez enquêter sans renvoyer les fichiers.

## Questions fréquentes

### Où trouver le secret de signature ?

Sur la page « Webhooks » du tableau de bord. Il commence par whsec_ et appartient à votre équipe. Vous pouvez le renouveler depuis cette page à tout moment.

### Que se passe-t-il si mon serveur ne répond pas ?

Nous retentons l’envoi avec des délais croissants, jusqu’à 6 tentatives au total sur environ une heure. Chaque tentative attend 10 secondes au maximum. Les redirections ne sont pas suivies.

### Puis-je utiliser un webhook avec MCP ?

Non. Les webhooks sont disponibles uniquement avec l’API REST. Les outils MCP attendent la transcription ou renvoient un ID à consulter ensuite.

## Pour aller plus loin

- [Webhooks (documentation)](https://transcript1.com/fr/docs/webhooks)
- [API audio et vidéo](https://transcript1.com/fr/features/speech-to-text-api)
- [Agents IA et LLM](https://transcript1.com/fr/use-cases/transcriptions-pour-agents-ia)