Webhooki i powiadomienia

Skonfiguruj automatyczne powiadomienia w czasie rzeczywistym o swoich transkrypcjach. Dowiedz się, jak skonfigurować webhooki, zaimplementować bezpieczeństwo i zintegrować je ze swoimi systemami.

Dlaczego warto używać webhooków?

Dostępne zdarzenia

| Zdarzenie | Opis | Ładunek | |---|---|---| | transcription.started | Transkrypcja rozpoczęła przetwarzanie | ID przesyłania, silnik, znacznik czasu | | transcription.progress | Postęp zaktualizowany | ID przesyłania, procent, oszacowanie | | transcription.completed | Transkrypcja zakończona sukcesem | ID przesyłania, tekst, czas trwania, kredyty | | transcription.failed | Transkrypcja nie powiodła się | ID przesyłania, błąd, typ błędu | | transcription.retry | Rozpoczęto próbę ponowienia | ID przesyłania, próba, silnik | | upload.completed | Przesyłanie pliku zakończone | ID przesyłania, rozmiar, format | | credits.low | Kredyty poniżej skonfigurowanego progu | Aktualny stan, próg |

Konfiguracja krok po kroku

Przykłady implementacji

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

Bezpieczeństwo i najlepsze praktyki

Najlepsze praktyki bezpieczeństwa:

• Weryfikuj podpis HMAC-SHA256 każdego żądania
• Używaj HTTPS na punkcie końcowym odbierającym
• Implementuj idempotentność (to samo zdarzenie przetworzone tylko raz)
• Okresowo rotuj sekret webhooka
• Rejestruj wszystkie otrzymane zdarzenia do audytu

Najlepsze praktyki implementacji:

• Odpowiadaj szybko (w ciągu 5 sekund) kodem 200 OK
• Przetwarzaj zdarzenia asynchronicznie
• Zaimplementuj kolejkę przetwarzania dla dużego obciążenia
• Monitoruj nieudane dostawy na panelu

Mechanizm ponawiania

Jeśli Twój punkt końcowy nie odpowie poprawnie (2xx), VoxScriber ponawia dostawę:

| Próba | Odstęp | Opis | |---|---|---| | 1 | Natychmiast | Pierwsza próba | | 2 | 1 minuta | Po początkowym niepowodzeniu | | 3 | 5 minut | Druga próba ponowna | | 4 | 30 minut | Trzecia próba ponowna | | 5 | 2 godziny | Ostatnia próba |

Po 5 kolejnych niepowodzeniach webhook jest automatycznie wyłączany, a Ty otrzymujesz powiadomienie e-mail.

Rozwiązywanie problemów

Webhook nie jest odbierany

Możliwe przyczyny: Nieprawidłowy adres URL, blokowanie przez zaporę sieciową, nieprawidłowy certyfikat SSL.

Rozwiązania: Sprawdź adres URL w panelu, zezwól na adres IP VoxScriber w swojej zaporze, zweryfikuj certyfikat SSL.

Nieprawidłowy podpis

Możliwe przyczyny: Nieprawidłowy sekret, inne kodowanie treści, middleware zmieniający treść.

Rozwiązania: Potwierdź sekret w panelu, używaj surowego ciała do weryfikacji, wyłącz middleware parsujące przed weryfikacją.

Zduplikowane zdarzenia

Możliwe przyczyny: Ponowienie po przekroczeniu limitu czasu, wolna odpowiedź serwera.

Rozwiązania: Zaimplementuj idempotentność za pomocą event.id, odpowiadaj szybko kodem 200 OK, przetwarzaj asynchronicznie.

Kontynuuj naukę

• Integracja API – Pełna dokumentacja API
• Automatyzacja przepływów pracy – Automatyzuj procesy za pomocą webhooków
• Przetwarzanie wsadowe – Transkrybuj wiele plików