Dois-je utiliser des webhooks ou du polling pour une API de transcription ?

Question

Accepted Answer

Webhooks pour la livraison principale, polling en secours – la configuration de production la plus robuste. Le polling seul gaspille des requêtes ; les webhooks seuls risquent de perdre des événements.

Les jobs de transcription sont généralement asynchrones : vous téléversez un fichier, l'API renvoie un `transcription.id`, et le résultat arrive plus tard. Comment savez-vous qu'il est prêt ?

**Polling**
Votre code interroge l'API périodiquement : « Le job X est-il terminé ? \" Typiquement : GET `/v1/transcriptions/{id}/status` toutes les 2 à 5 secondes. Quand le statut passe à `completed`, vous récupérez le résultat.

Avantages : simple, aucune URL publique nécessaire, fonctionne derrière les pare-feu et dans les jobs en arrière-plan.
Inconvénients : beaucoup de requêtes vides (un fichier d'1 h traité en 2 min coûte 60 à 100 sondages), risque de limite de débit, latence max = intervalle de polling.

**Webhooks**
Vous enregistrez une URL ; l'API l'appelle quand le job se termine. POST avec un corps du type `{ "event": "transcription.completed", "id": "…", "result": { … } }`. Signé avec HMAC-SHA256 pour que vous puissiez vérifier qu'il s'agit bien du prestataire.

Avantages : aucune requête vide, latence inférieure à la seconde, passe à l'échelle de millions de jobs.
Inconvénients : nécessite une URL publique (ou un tunnel comme ngrok en dev), vous devez implémenter vous-même les nouvelles tentatives, l'idempotence et la vérification de signature. Si la livraison du webhook échoue (serveur indisponible, coupure réseau), l'événement peut être perdu.

**La bonne réponse : les deux**
Les systèmes en production combinent les deux. Webhooks pour la livraison principale – rapide, efficace. Polling en filet de sécurité toutes les 5 à 10 minutes pour les jobs en file depuis plus de 30 min – rattrape les cas où le webhook a été perdu.

**Pattern concret**
```
// Au téléversement
const job = await api.transcribe({ file, webhook_url: "https://…" })
await db.insert({ id: job.id, status: "queued" })

// Endpoint du webhook
app.post("/webhook", (req) => {
  if (!verifySignature(req)) return 401
  await db.update(req.body.id, { status: "completed", result: req.body.result })
})

// Job de secours (cron, toutes les 10 min)
const stuck = await db.where("status", "queued").and("createdAt", "<", now-30min)
for (const j of stuck) {
  const fresh = await api.getStatus(j.id)
  if (fresh.status === "completed") await db.update(j.id, fresh)
}
```

**Spécificités DeepScript**
Nous prenons en charge les deux : enregistrez des webhooks via `POST /v1/webhooks` (événements : `transcription.completed`, `transcription.failed`, `balance.low`), faites du polling via `GET /v1/transcriptions/{id}/status`. Pour une interface en temps réel dans le navigateur, nous proposons aussi le SSE (`GET /v1/transcriptions/{id}/events`) – les server-sent events diffusent les mises à jour de statut directement vers le client sans ouvrir de canal WebSocket.

Dois-je utiliser des webhooks ou du polling pour une API de transcription ?

Questions associées

Une question reste sans réponse ?