Webhooks og varsler

Sett opp sanntidsvarsler om transkriberingene dine. Lær hvordan du konfigurerer webhooks, implementerer sikkerhet og integrerer dem med systemene dine.

Hvorfor bruke webhooks?

Tilgjengelige hendelser

| Event | Description | Payload | |---|---|---| | transcription.started | Transkribering startet behandling | Upload ID, engine, timestamp | | transcription.progress | Fremdrift oppdatert | Upload ID, percentage, estimate | | transcription.completed | Transkribering fullført vellykket | Upload ID, text, duration, credits | | transcription.failed | Transkribering mislyktes | Upload ID, error, error type | | transcription.retry | Nytt forsøk startet | Upload ID, attempt, engine | | upload.completed | Filopplasting fullført | Upload ID, size, format | | credits.low | Kreditter under konfigurert terskel | Current balance, threshold |

Trinn-for-trinn-konfigurasjon

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

Sikkerhet og beste praksis

Sikkerhetsbeste praksis:

• Valider HMAC-SHA256-signaturen for hver forespørsel
• Bruk HTTPS på mottakerendepunktet
• Implementer idempotens (samme hendelse behandles kun én gang)
• Roter webhook-hemmeligheten jevnlig
• Logg alle mottatte hendelser for revisjon

Implementeringsbeste praksis:

• Svar raskt med 200 OK (innen 5 sekunder)
• Behandle hendelser asynkront
• Implementer en behandlingskø for høy belastning
• Overvåk leveringsfeil i dashbordet

Gjentaksmekanisme

Når endepunktet ditt ikke svarer vellykket (2xx), prøver VoxScriber leveringen på nytt:

| Forsøk | Intervall | Beskrivelse | |---|---|---| | 1 | Umiddelbart | Første forsøk | | 2 | 1 minutt | Etter første feil | | 3 | 5 minutter | Andre forsøk | | 4 | 30 minutter | Tredje forsøk | | 5 | 2 timer | Siste forsøk |

Etter 5 sammenhengende feil deaktiveres webhooken automatisk og du mottar en e-postvarsling.

Feilsøking

Webhooken mottas ikke

Mulige årsaker: Feil URL, brannmur som blokkerer, ugyldig SSL-sertifikat.

Løsninger: Kontroller URL-en i dashbordet, tillat VoxScripter's IP i brannmuren, valider SSL-sertifikatet ditt.

Ugyldig signatur

Mulige årsaker: Feil hemmelighet, forskjellig kroppskoding, mellomvare som endrer kroppen.

Løsninger: Bekreft hemmeligheten i dashbordet, bruk rå kropp for verifisering, deaktiver parserende mellomvare før verifisering.

Duplikathendelser

Mulige årsaker: Gjentak etter tidsavbrudd, treg serverrespons.

Løsninger: Implementer idempotens ved hjelp av event.id, svar raskt med 200 OK, behandl asynkront.

Fortsett å lære

• API-integrasjon – Full API-dokumentasjon
• Arbeidsflytautomatisering – Automatiser prosesser med webhooks
• Batchbehandling – Transkriber flere filer