Webhooky a notifikace

Nastavte automatická upozornění o výsledcích přepisů v reálném čase. Zjistěte, jak konfigurovat webhooky, implementovat zabezpečení a integrovat je se svými systémy.

Proč používat webhooky?

Dostupné události

| Událost | Popis | Payload | |---|---|---| | transcription.started | Zahájeno zpracování přepisu | ID nahrávky, engine, časové razítko | | transcription.progress | Aktualizace průběhu | ID nahrávky, procento, odhad | | transcription.completed | Přepis úspěšně dokončen | ID nahrávky, text, délka, kredity | | transcription.failed | Přepis selhal | ID nahrávky, chyba, typ chyby | | transcription.retry | Zahájen pokus o opakování | ID nahrávky, pokus, engine | | upload.completed | Nahrávání souboru dokončeno | ID nahrávky, velikost, formát | | credits.low | Kredity klesly pod nastavený limit | Aktuální zůstatek, limit |

Postup konfigurace

Příklady implementace

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) => {
  // Ověření podpisu
  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('Neplatný podpis');
  }

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

  switch (event.type) {
    case 'transcription.completed':
      console.log('Přepis dokončen:', event.data.uploadId);
      // Zpracování výsledku
      break;
    case 'transcription.failed':
      console.log('Přepis selhal:', event.data.error);
      // Ošetření chyby
      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():
    # Ověření podpisu
    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': 'Neplatný podpis'}), 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

Zabezpečení a osvědčené postupy

Bezpečnostní osvědčené postupy:

• Ověřujte HMAC-SHA256 podpis každého požadavku
• Používejte HTTPS na přijímacím koncovém bodu
• Implementujte idempotenci (stejná událost zpracována pouze jednou)
• Pravidelně obměňujte tajný klíč webhooku
• Logujte všechny přijaté události pro audit

Implementační osvědčené postupy:

• Odpovídejte 200 OK rychle (do 5 sekund)
• Zpracovávejte události asynchronně
• Pro vysokou zátěž implementujte frontu zpracování
• Sledujte chyby doručení na dashboardu

Mechanismus opakování

Pokud váš koncový bod neodpoví úspěšně (2xx), VoxScriber opakuje doručení:

| Pokus | Interval | Popis | |---|---|---| | 1 | Ihned | První pokus | | 2 | 1 minuta | Po prvním selhání | | 3 | 5 minut | Druhé opakování | | 4 | 30 minut | Třetí opakování | | 5 | 2 hodiny | Poslední pokus |

Po 5 po sobě jdoucích selháních je webhook automaticky deaktivován a obdržíte e-mailové upozornění.

Řešení problémů

Webhook není přijímán

Možné příčiny: Nesprávná URL, blokování firewallem, neplatný SSL certifikát.

Řešení: Zkontrolujte URL v dashboardu, povolte IP adresu VoxScriberu ve firewallu, ověřte svůj SSL certifikát.

Neplatný podpis

Možné příčiny: Nesprávný tajný klíč, odlišné kódování těla, middleware měnící tělo požadavku.

Řešení: Potvrďte tajný klíč v dashboardu, použijte surové tělo pro ověření, před ověřením zakažte middleware pro parsování.

Duplicitní události

Možné příčiny: Opakování po timeoutu, pomalá odpověď serveru.

Řešení: Implementujte idempotenci pomocí event.id, rychle odpovídejte 200 OK, zpracovávejte asynchronně.

Další zdroje

• API integrace - Kompletní API dokumentace
• Automatizace pracovních postupů - Automatizujte procesy pomocí webhooků
• Dávkové zpracování - Přepis více souborů najednou