Webhookと通知

文字起こしに関するリアルタイムの自動通知を設定します。Webhookの構成方法、セキュリティの実装、システムとの統合について学びます。

Webhookを使用する理由

利用可能なイベント

| イベント | 説明 | ペイロード | |---|---|---| | transcription.started | 文字起こし処理が開始されました | アップロードID, エンジン, タイムスタンプ | | transcription.progress | 進捗が更新されました | アップロードID, パーセンテージ, 推定時間 | | transcription.completed | 文字起こしが正常に完了しました | アップロードID, テキスト, 時間, クレジット | | transcription.failed | 文字起こしに失敗しました | アップロードID, エラー, エラータイプ | | transcription.retry | 再試行が開始されました | アップロードID, 試行回数, エンジン | | upload.completed | ファイルのアップロードが完了しました | アップロードID, サイズ, フォーマット | | credits.low | クレジットが設定されたしきい値を下回っています | 現在の残高, しきい値 |

ステップバイステップの設定

実装例

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

セキュリティとベストプラクティス

セキュリティのベストプラクティス:

• 各リクエストのHMAC-SHA256署名を検証する
• 受信エンドポイントにHTTPSを使用する
• 冪等性を実装する（同じイベントは一度だけ処理される）
• Webhookシークレットを定期的にローテーションする
• 監査のためにすべての受信イベントをログに記録する

実装のベストプラクティス:

• 素早く200 OKで応答する（5秒以内）
• イベントを非同期で処理する
• 高負荷時に備えて処理キューを実装する
• ダッシュボードで配信障害を監視する

再試行メカニズム

エンドポイントが正常に応答しない（2xx以外）場合、VoxScriberは配信を再試行します。

| 試行 | 間隔 | 説明 | |---|---|---| | 1 | 即時 | 最初の試行 | | 2 | 1分 | 初回失敗後 | | 3 | 5分 | 2回目の再試行 | | 4 | 30分 | 3回目の再試行 | | 5 | 2時間 | 最終試行 |

5回連続で失敗すると、Webhookは自動的に無効になり、メール通知が届きます。

トラブルシューティング

Webhookが受信されない

考えられる原因: URLが正しくない、ファイアウォールがブロックしている、SSL証明書が無効。

解決策: ダッシュボードでURLを確認し、ファイアウォールでVoxScriberのIPを許可し、SSL証明書を検証してください。

署名が無効

考えられる原因: シークレットが間違っている、ボディのエンコードが異なる、ミドルウェアがボディを変更している。

解決策: ダッシュボードでシークレットを確認し、生のボディを使用して検証し、検証前にパーシングミドルウェアを無効にしてください。

重複したイベント

考えられる原因: タイムアウト後の再試行、サーバーの応答が遅い。

解決策: event.idを使用して冪等性を実装し、素早く200 OKで応答し、非同期で処理してください。

学習を続ける

• API統合 - 完全なAPIドキュメント
• ワークフローの自動化 - Webhookを使ったプロセス自動化
• バッチ処理 - 複数ファイルの文字起こし