Webhooks & meldingen

Stel realtime automatische meldingen in over uw transcripties. Leer hoe u webhooks configureert, beveiliging implementeert en integreert met uw systemen.

Waarom webhooks gebruiken?

Beschikbare gebeurtenissen

| Gebeurtenis | Beschrijving | Payload | |---|---|---| | transcription.started | Transcriptie is gestart met verwerken | Upload-ID, engine, tijdstempel | | transcription.progress | Voortgang bijgewerkt | Upload-ID, percentage, schatting | | transcription.completed | Transcriptie succesvol voltooid | Upload-ID, tekst, duur, credits | | transcription.failed | Transcriptie mislukt | Upload-ID, fout, fouttype | | transcription.retry | Herhalingspoging gestart | Upload-ID, poging, engine | | upload.completed | Bestandsupload voltooid | Upload-ID, grootte, formaat | | credits.low | Credits onder de ingestelde drempel | Huidig saldo, drempel |

Stapsgewijze configuratie

Implementatievoorbeelden

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

Beveiliging & best practices

Best practices voor beveiliging:

• Valideer de HMAC-SHA256-handtekening van elk verzoek
• Gebruik HTTPS op het ontvangende eindpunt
• Implementeer idempotentie (dezelfde gebeurtenis slechts één keer verwerken)
• Verander het webhook-geheim periodiek
• Log alle ontvangen gebeurtenissen voor auditing

Best practices voor implementatie:

• Reageer snel met 200 OK (binnen 5 seconden)
• Verwerk gebeurtenissen asynchroon
• Implementeer een verwerkingswachtrij voor hoge belasting
• Monitor leveringsfouten in het dashboard

Herhalingmechanisme

Wanneer uw eindpunt niet succesvol reageert (2xx), probeert VoxScriber de levering opnieuw:

| Poging | Interval | Beschrijving | |---|---|---| | 1 | Onmiddellijk | Eerste poging | | 2 | 1 minuut | Na eerste mislukking | | 3 | 5 minuten | Tweede herhaling | | 4 | 30 minuten | Derde herhaling | | 5 | 2 uur | Laatste poging |

Na 5 opeenvolgende mislukkingen wordt de webhook automatisch uitgeschakeld en ontvangt u een e-mailmelding.

Probleemoplossing

Webhook wordt niet ontvangen

Mogelijke oorzaken: Onjuiste URL, firewall blokkeert, ongeldig SSL-certificaat.

Oplossingen: Controleer de URL in het dashboard, sta het IP van VoxScriber toe in uw firewall, valideer uw SSL-certificaat.

Ongeldige handtekening

Mogelijke oorzaken: Onjuist geheim, andere body-codering, middleware die de body wijzigt.

Oplossingen: Bevestig het geheim in het dashboard, gebruik de ruwe body voor verificatie, schakel parseer-middleware uit vóór verificatie.

Dubbele gebeurtenissen

Mogelijke oorzaken: Herhaling na timeout, trage serverrespons.

Oplossingen: Implementeer idempotentie met event.id, reageer snel met 200 OK, verwerk asynchroon.

Verder leren

• API Integration - Volledige API-documentatie
• Workflow Automation - Automatiseer processen met webhooks
• Batch Processing - Transcribeer meerdere bestanden