Webhooks et Notifications

Configurez des notifications automatiques en temps réel sur vos transcriptions. Apprenez à configurer des webhooks, à implémenter la sécurité et à intégrer avec vos systèmes.

Pourquoi Utiliser des Webhooks ?

Événements Disponibles

| Événement | Description | Payload | |---|---|---| | transcription.started | La transcription a commencé le traitement | Upload ID, moteur, horodatage | | transcription.progress | Progression mise à jour | Upload ID, pourcentage, estimation | | transcription.completed | Transcription terminée avec succès | Upload ID, texte, durée, crédits | | transcription.failed | La transcription a échoué | Upload ID, erreur, type d'erreur | | transcription.retry | Tentative de retry lancée | Upload ID, tentative, moteur | | upload.completed | Upload de fichier terminé | Upload ID, taille, format | | credits.low | Crédits en dessous du seuil configuré | Solde actuel, seuil |

Configuration Pas à Pas

Exemples d'Implémentation

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/vozparatexto', express.raw({ type: 'application/json' }), (req, res) => {
  // Vérifier la signature
  const signature = req.headers['x-webhook-signature'];
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== hash) {
    return res.status(401).send('Signature invalide');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'transcription.completed':
      console.log('Transcription terminée :', event.data.uploadId);
      // Traiter le résultat
      break;
    case 'transcription.failed':
      console.log('Transcription échouée :', event.data.error);
      // Gérer l'erreur
      break;
  }

  res.status(200).json({ received: true });
});

Python (Flask)

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

@app.route('/webhook/vozparatexto', methods=['POST'])
def handle_webhook():
    # Vérifier la signature
    signature = request.headers.get('X-Webhook-Signature')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Signature invalide'}), 401

    event = request.json

    if event['type'] == 'transcription.completed':
        process_transcription(event['data'])
    elif event['type'] == 'transcription.failed':
        handle_failure(event['data'])

    return jsonify({'received': True}), 200

Sécurité et Bonnes Pratiques

Bonnes pratiques de sécurité :

• Validez la signature HMAC-SHA256 de chaque requête
• Utilisez HTTPS pour l'endpoint de réception
• Implémentez l'idempotence (même événement traité une seule fois)
• Renouvelez le secret du webhook périodiquement
• Enregistrez tous les événements reçus à des fins d'audit

Bonnes pratiques d'implémentation :

• Répondez avec 200 OK rapidement (dans les 5 secondes)
• Traitez les événements de manière asynchrone
• Implémentez une file de traitement pour les charges élevées
• Surveillez les échecs de livraison dans le tableau de bord

Mécanisme de Retry

Lorsque votre endpoint ne répond pas avec succès (2xx), Voix2Texte tente de renvoyer :

| Tentative | Intervalle | Description | |---|---|---| | 1 | Immédiat | Première tentative | | 2 | 1 minute | Après l'échec initial | | 3 | 5 minutes | Deuxième nouvelle tentative | | 4 | 30 minutes | Troisième nouvelle tentative | | 5 | 2 heures | Dernière tentative |

Après 5 échecs consécutifs, le webhook est automatiquement désactivé et vous recevez une notification par e-mail.

Résolution de Problèmes

Le webhook n'est pas reçu

Causes possibles : URL incorrecte, pare-feu bloquant, certificat SSL invalide.

Solutions : Vérifiez l'URL dans le tableau de bord, autorisez l'IP de Voix2Texte dans le pare-feu, validez votre certificat SSL.

Signature invalide

Causes possibles : Secret incorrect, encodage du body différent, middleware modifiant le body.

Solutions : Confirmez le secret dans le tableau de bord, utilisez le body brut pour la vérification, désactivez le middleware de parsing avant la vérification.

Événements en double

Causes possibles : Retry après timeout, réponse lente de votre serveur.

Solutions : Implémentez l'idempotence en utilisant l'event.id, répondez 200 OK rapidement, traitez de manière asynchrone.

Continuer à apprendre

• Intégration API - Documentation complète de l'API
• Automatisation des Flux - Automatisez vos processus avec les webhooks
• Traitement par Lot - Transcrivez plusieurs fichiers