Webhooks & Benachrichtigungen

Richten Sie automatische Echtzeit-Benachrichtigungen über Ihre Transkriptionen ein. Erfahren Sie, wie Sie Webhooks konfigurieren, Sicherheit implementieren und in Ihre Systeme integrieren.

Warum Webhooks verwenden?

Verfügbare Ereignisse

| Ereignis | Beschreibung | Nutzlast | |---|---|---| | transcription.started | Transkription gestartet | Upload-ID, Engine, Zeitstempel | | transcription.progress | Fortschritt aktualisiert | Upload-ID, Prozentsatz, Schätzung | | transcription.completed | Transkription erfolgreich abgeschlossen | Upload-ID, Text, Dauer, Credits | | transcription.failed | Transkription fehlgeschlagen | Upload-ID, Fehler, Fehlertyp | | transcription.retry | Wiederholungsversuch gestartet | Upload-ID, Versuch, Engine | | upload.completed | Datei-Upload abgeschlossen | Upload-ID, Größe, Format | | credits.low | Guthaben unter konfigurierter Schwelle | Aktueller Saldo, Schwelle |

Schritt-für-Schritt-Konfiguration

Implementierungsbeispiele

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

Sicherheit & bewährte Methoden

Sicherheitsempfehlungen:

• Validieren Sie die HMAC-SHA256-Signatur jeder Anfrage
• Verwenden Sie HTTPS am empfangenden Endpunkt
• Implementieren Sie Idempotenz (gleiches Ereignis nur einmal verarbeitet)
• Wechseln Sie das Webhook-Geheimnis regelmäßig
• Protokollieren Sie alle empfangenen Ereignisse zur Prüfung

Implementierungsempfehlungen:

• Antworten Sie schnell mit 200 OK (innerhalb von 5 Sekunden)
• Verarbeiten Sie Ereignisse asynchron
• Implementieren Sie eine Verarbeitungswarteschlange bei hoher Last
• Überwachen Sie Zustellungsfehler im Dashboard

Wiederholungsmechanismus

Wenn Ihr Endpunkt nicht erfolgreich antwortet (2xx), wiederholt VoxScriber die Zustellung:

| Versuch | Intervall | Beschreibung | |---|---|---| | 1 | Sofort | Erster Versuch | | 2 | 1 Minute | Nach erstem Fehlschlag | | 3 | 5 Minuten | Zweiter Versuch | | 4 | 30 Minuten | Dritter Versuch | | 5 | 2 Stunden | Letzter Versuch |

Nach 5 aufeinanderfolgenden Fehlschlägen wird der Webhook automatisch deaktiviert und Sie erhalten eine E-Mail-Benachrichtigung.

Fehlerbehebung

Webhook wird nicht empfangen

Mögliche Ursachen: Falsche URL, Firewall blockiert, ungültiges SSL-Zertifikat.

Lösungen: Überprüfen Sie die URL im Dashboard, erlauben Sie die IP von VoxScriber in Ihrer Firewall, validieren Sie Ihr SSL-Zertifikat.

Ungültige Signatur

Mögliche Ursachen: Falsches Geheimnis, unterschiedliche Body-Kodierung, Middleware verändert den Body.

Lösungen: Bestätigen Sie das Geheimnis im Dashboard, verwenden Sie den rohen Body zur Prüfung, deaktivieren Sie die Parsing-Middleware vor der Prüfung.

Doppelte Ereignisse

Mögliche Ursachen: Wiederholung nach Timeout, langsame Serverantwort.

Lösungen: Implementieren Sie Idempotenz mit der event.id, antworten Sie schnell mit 200 OK, verarbeiten Sie asynchron.

Weiterführende Themen

• API-Integration – Vollständige API-Dokumentation
• Workflow-Automatisierung – Prozesse mit Webhooks automatisieren
• Stapelverarbeitung – Mehrere Dateien transkribieren