Webhooks & Notifikationer

Opsæt realtidsautomatiske notifikationer om dine transskriptioner. Lær, hvordan du konfigurerer webhooks, implementerer sikkerhed og integrerer med dine systemer.

Hvorfor bruge webhooks?

Tilgængelige hændelser

| Hændelse | Beskrivelse | Nyttelast | |---|---|---| | transcription.started | Transskription startede behandling | Upload-id, motor, tidsstempel | | transcription.progress | Fremskridt opdateret | Upload-id, procent, estimat | | transcription.completed | Transskription fuldført | Upload-id, tekst, varighed, kreditter | | transcription.failed | Transskription mislykkedes | Upload-id, fejl, fejltype | | transcription.retry | Genforsøg startet | Upload-id, forsøg, motor | | upload.completed | Filupload fuldført | Upload-id, størrelse, format | | credits.low | Kreditter under konfigureret grænse | Nuværende saldo, grænse |

Trin-for-trin konfiguration

Implementeringseksempler

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

Sikkerhed & bedste praksis

Bedste praksis for sikkerhed:

• Valider HMAC-SHA256-signaturen for hver forespørgsel
• Brug HTTPS på det modtagende slutpunkt
• Implementér idempotens (samme hændelse behandles kun én gang)
• Roter webhook-hemmeligheden periodisk
• Log alle modtagne hændelser til revision

Bedste praksis for implementering:

• Svar hurtigt med 200 OK (inden for 5 sekunder)
• Behandl hændelser asynkront
• Implementér en behandlingskø til høj belastning
• Overvåg leveringsfejl på dashboardet

Gentagelsesmekanisme

Når dit slutpunkt ikke svarer succesfuldt (2xx), gentager VoxScriber leveringen:

| Forsøg | Interval | Beskrivelse | |---|---|---| | 1 | Øjeblikkeligt | Første forsøg | | 2 | 1 minut | Efter første fejl | | 3 | 5 minutter | Andet genforsøg | | 4 | 30 minutter | Tredje genforsøg | | 5 | 2 timer | Sidste forsøg |

Efter 5 på hinanden følgende fejl deaktiveres webhook'en automatisk, og du modtager en e-mail-notifikation.

Fejlfinding

Webhook modtages ikke

Mulige årsager: Forkert URL, firewall-blokering, ugyldigt SSL-certifikat.

Løsninger: Verificér URL'en i dashboardet, tillad VoxScriber's IP i din firewall, valider dit SSL-certifikat.

Ugyldig signatur

Mulige årsager: Forkert hemmelighed, anderledes kropskodning, middleware der ændrer kropsindholdet.

Løsninger: Bekræft hemmeligheden i dashboardet, brug den rå krop til verifikation, deaktivér parsing-middleware før verifikation.

Duplikathændelser

Mulige årsager: Genforsøg efter timeout, langsom serverrespons.

Løsninger: Implementér idempotens ved at bruge event.id, svar hurtigt med 200 OK, behandl asynkront.

Fortsæt med at lære

• API-integration - Fuld API-dokumentation
• Workflow-automatisering - Automatiser processer med webhooks
• Batch-behandling - Transskriber flere filer