Webhook e Notifiche

Configura notifiche automatiche in tempo reale per le tue trascrizioni. Scopri come impostare i webhook, implementare la sicurezza e integrarli con i tuoi sistemi.

Perché usare i webhook?

Eventi disponibili

| Evento | Descrizione | Payload | |---|---|---| | transcription.started | Trascrizione avviata in elaborazione | ID upload, motore, timestamp | | transcription.progress | Progresso aggiornato | ID upload, percentuale, stima | | transcription.completed | Trascrizione completata con successo | ID upload, testo, durata, crediti | | transcription.failed | Trascrizione fallita | ID upload, errore, tipo di errore | | transcription.retry | Tentativo di riprova avviato | ID upload, tentativo, motore | | upload.completed | Caricamento file completato | ID upload, dimensione, formato | | credits.low | Crediti al di sotto della soglia configurata | Saldo attuale, soglia |

Configurazione passo passo

Esempi di implementazione

Node.js (Express)

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

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

app.post('/webhook/voxscriber', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify 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('Invalid signature');
  }

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

  switch (event.type) {
    case 'transcription.completed':
      console.log('Transcription completed:', event.data.uploadId);
      // Process result
      break;
    case 'transcription.failed':
      console.log('Transcription failed:', event.data.error);
      // Handle error
      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/voxscriber', methods=['POST'])
def handle_webhook():
    # Verify 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': 'Invalid signature'}), 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

Sicurezza e buone pratiche

Buone pratiche di sicurezza:

• Convalida la firma HMAC-SHA256 di ogni richiesta
• Usa HTTPS sull'endpoint ricevente
• Implementa l'idempotenza (lo stesso evento elaborato una sola volta)
• Ruota periodicamente il segreto del webhook
• Registra tutti gli eventi ricevuti per audit

Buone pratiche di implementazione:

• Rispondi con 200 OK rapidamente (entro 5 secondi)
• Elabora gli eventi in modo asincrono
• Implementa una coda di elaborazione per carichi elevati
• Monitora i fallimenti di consegna sulla dashboard

Meccanismo di riprova

Quando il tuo endpoint non risponde con successo (2xx), VoxScriber riprova la consegna:

| Tentativo | Intervallo | Descrizione | |---|---|---| | 1 | Immediato | Primo tentativo | | 2 | 1 minuto | Dopo il fallimento iniziale | | 3 | 5 minuti | Secondo tentativo | | 4 | 30 minuti | Terzo tentativo | | 5 | 2 ore | Tentativo finale |

Dopo 5 fallimenti consecutivi, il webhook viene automaticamente disabilitato e ricevi una notifica via email.

Risoluzione dei problemi

Il webhook non viene ricevuto

Possibili cause: URL errato, blocco del firewall, certificato SSL non valido.

Soluzioni: Verifica l'URL nella dashboard, autorizza l'IP di VoxScriber nel tuo firewall, convalida il tuo certificato SSL.

Firma non valida

Possibili cause: Segreto errato, codifica del corpo diversa, middleware che altera il corpo.

Soluzioni: Conferma il segreto nella dashboard, usa il corpo grezzo per la verifica, disabilita il middleware di parsing prima della verifica.

Eventi duplicati

Possibili cause: Riprova dopo timeout, risposta lenta del server.

Soluzioni: Implementa l'idempotenza usando event.id, rispondi con 200 OK rapidamente, elabora in modo asincrono.

Continua ad imparare

• Integrazione API - Documentazione completa dell'API
• Automazione dei flussi di lavoro - Automatizza i processi con i webhook
• Elaborazione in lotti - Trascrivi più file