الويبهوكس والإشعارات

قم بإعداد الإشعارات التلقائية في الوقت الفعلي لعمليات النسخ الخاصة بك. تعرف على كيفية تكوين الويبهوكس، وتنفيذ الأمان، والتكامل مع أنظمتك.

لماذا استخدام الويبهوكس؟

الأحداث المتاحة

| الحدث | الوصف | الحمولة | |---|---|---| | transcription.started | بدأت معالجة النسخ | Upload ID, engine, timestamp | | transcription.progress | تم تحديث التقدم | Upload ID, percentage, estimate | | transcription.completed | اكتمل النسخ بنجاح | Upload ID, text, duration, credits | | transcription.failed | فشل النسخ | Upload ID, error, error type | | transcription.retry | بدأت محاولة إعادة المحاولة | Upload ID, attempt, engine | | upload.completed | اكتمل تحميل الملف | Upload ID, size, format | | credits.low | الرصيد أقل من الحد المكون | Current balance, threshold |

التكوين خطوة بخطوة

أمثلة على التنفيذ

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 | دقيقة واحدة | بعد الفشل الأولي | | 3 | 5 دقائق | إعادة المحاولة الثانية | | 4 | 30 دقيقة | إعادة المحاولة الثالثة | | 5 | ساعتان | المحاولة النهائية |

بعد 5 إخفاقات متتالية، يتم تعطيل الويبهوك تلقائيًا وتتلقى إشعارًا عبر البريد الإلكتروني.

استكشاف الأخطاء وإصلاحها

عدم استلام الويبهوك

الأسباب المحتملة: عنوان URL غير صحيح، حظر جدار الحماية، شهادة SSL غير صالحة.

الحلول: تحقق من عنوان URL في لوحة التحكم، اسمح بعنوان IP الخاص بـ VoxScriber في جدار الحماية، تحقق من صحة شهادة SSL الخاصة بك.

توقيع غير صالح

الأسباب المحتملة: سر غير صحيح، ترميز مختلف للنص، برمجية وسيطة تغير النص.

الحلول: تأكيد السر في لوحة التحكم، استخدم النص الخام للتحقق، قم بتعطيل برمجية التحليل الوسيطة قبل التحقق.

أحداث مكررة

الأسباب المحتملة: إعادة المحاولة بعد انتهاء المهلة، استجابة خادم بطيئة.

الحلول: تنفيذ التكرارية باستخدام event.id، الرد بسرعة بـ 200 OK، المعالجة بشكل غير متزامن.

مواصلة التعلم

• تكامل API - وثائق API الكاملة
• أتمتة سير العمل - أتمتة العمليات باستخدام الويبهوكس
• المعالجة المجمعة - نسخ ملفات متعددة