웹훅 및 알림

전사에 대한 실시간 자동 알림을 설정하세요. 웹훅 구성, 보안 구현, 시스템 통합 방법을 알아보세요.

웹훅을 사용하는 이유?

사용 가능한 이벤트

| 이벤트 | 설명 | 페이로드 | |---|---|---| | 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 사용
• 멱등성 구현 (동일 이벤트가 한 번만 처리됨)
• 웹훅 시크릿 주기적으로 교체
• 감사용으로 수신된 모든 이벤트 기록

구현 모범 사례:

• 빠르게 200 OK 응답 (5초 이내)
• 비동기적으로 이벤트 처리
• 높은 부하를 위한 처리 큐 구현
• 대시보드에서 전송 실패 모니터링

재시도 메커니즘

엔드포인트가 성공(2xx)으로 응답하지 않으면 VoxScriber가 전송을 재시도합니다:

| 시도 | 간격 | 설명 | |---|---|---| | 1 | 즉시 | 첫 번째 시도 | | 2 | 1분 | 초기 실패 후 | | 3 | 5분 | 두 번째 재시도 | | 4 | 30분 | 세 번째 재시도 | | 5 | 2시간 | 마지막 시도 |

5회 연속 실패 후 웹훅이 자동으로 비활성화되며 이메일 알림이 발송됩니다.

문제 해결

웹훅이 수신되지 않음

가능한 원인: 잘못된 URL, 방화벽 차단, 유효하지 않은 SSL 인증서.

해결 방법: 대시보드에서 URL 확인, 방화벽에서 VoxScriber IP 허용, SSL 인증서 검증.

잘못된 서명

가능한 원인: 잘못된 시크릿, 다른 본문 인코딩, 미들웨어가 본문을 변경함.

해결 방법: 대시보드에서 시크릿 확인, 검증에 원시 본문 사용, 검증 전 파싱 미들웨어 비활성화.

중복 이벤트

가능한 원인: 시간 초과 후 재시도, 느린 서버 응답.

해결 방법: event.id를 사용한 멱등성 구현, 빠르게 200 OK 응답, 비동기 처리.

계속 학습

• API 통합 - 완전한 API 문서
• 워크플로우 자동화 - 웹훅으로 프로세스 자동화
• 일괄 처리 - 여러 파일 전사