Webhook уведомления

Webhook уведомления

Когда задача завершается, API отправляет POST запрос на указанный webhook_url со следующими данными:

Пример webhook уведомления

{
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "job_state": "done",
    "requested_actions": ["transcript", "summary", "quiz", "timecodes"],
    "transcript": {
        "transcript_id": "transcript-uuid",
        "status": "done",
        "cues": [
            {
                "start_time": 0.0,
                "end_time": 5.5,
                "text": "Привет, добро пожаловать на наш канал",
                "speaker": "Спикер 1"
            }
        ],
        "full_text": "Привет, добро пожаловать на наш канал. Сегодня мы расскажем..."
    },
    "summary": {
        "summary_id": "summary-uuid", 
        "status": "done",
        "html": "<h1>Краткое изложение</h1><p>В данном видео рассматриваются...</p>"
    },
    "quiz": {
        "quiz_id": "quiz-uuid",
        "status": "done",
        "data": [
            {
                "question": "О чем рассказывается в видео?",
                "options": ["О программировании", "О кулинарии", "О путешествиях"],
                "correct_answer": 0,
                "explanation": "В видео рассматриваются основы программирования"
            }
        ]
    },
    "timecodes": {
        "timecodes_id": "timecodes-uuid",
        "status": "done",
        "timecodes": [
            {
                "start_time": 0.0,
                "end_time": 30.0,
                "title": "Введение",
                "description": "Приветствие и обзор темы"
            }
        ]
    },
    "frames": [
        {
            "time": 10.5,
            "frame_url": "https://your-domain.com/frames/frame_001.jpg"
        }
    ],
    "webhook_url": "https://your-site.com/webhook"
}

Описание полей webhook

Основные поля

• job_id - UUID завершенной задачи

• job_state - Статус задачи (done или failed)

• requested_actions - Список запрошенных действий обработки

• webhook_url - URL, на который отправлен webhook

Продукты обработки

Каждый продукт включает:

• Статус (status) - done, failed или in_progress

• Внешний ID - UUID продукта во внешней системе

• Содержимое - Полные данные продукта (при успешной обработке)

Transcript (расшифровка)

• transcript_id - UUID расшифровки

• cues - Массив временных меток с текстом и спикерами

• full_text - Полный текст расшифровки

Summary (краткое изложение)

• summary_id - UUID краткого изложения

• html - HTML содержимое краткого изложения

Quiz (квиз)

• quiz_id - UUID квиза

• data - Массив вопросов с вариантами ответов

Timecodes (временные метки)

• timecodes_id - UUID временных меток

• timecodes - Массив временных интервалов с описанием

Frames (кадры)

• frames - Массив кадров с временными метками и URL изображений

Обработка webhook уведомлений

Требования к endpoint

Ваш webhook endpoint должен:

1. Принимать POST запросы с Content-Type: application/json

2. Возвращать HTTP 200 для подтверждения получения

3. Обрабатывать запросы быстро (рекомендуется < 10 секунд)

4. Быть доступным по HTTP/HTTPS

Пример обработчика (Python/Flask)

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    try:
        data = request.get_json()
        
        job_id = data.get('job_id')
        job_state = data.get('job_state')
        
        print(f"Job {job_id} completed with state: {job_state}")
        
        # Обработка продуктов
        if 'transcript' in data and data['transcript']['status'] == 'done':
            transcript = data['transcript']
            print(f"Transcript ready: {len(transcript['cues'])} segments")
            
        if 'summary' in data and data['summary']['status'] == 'done':
            summary = data['summary']
            print(f"Summary ready: {summary['summary_id']}")
        
        # Сохранение данных в базу данных
        # save_job_results(data)
        
        return jsonify({"status": "success"}), 200
        
    except Exception as e:
        print(f"Webhook error: {e}")
        return jsonify({"status": "error", "message": str(e)}), 400

Отладка webhook

Тестовый endpoint

API предоставляет тестовый endpoint /test_webhook/ для отладки:

curl -X POST "https://your-domain.com/test_webhook/" \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Логирование

Все webhook уведомления логируются на стороне API. При проблемах с доставкой обратитесь в поддержку с указанием job_id.

Безопасность

1. Проверка источника - Рекомендуется проверять IP-адрес отправителя

2. Таймауты - Настройте разумные таймауты для обработки

3. Валидация - Всегда валидируйте входящие данные

Устранение неполадок

Частые проблемы

1. Webhook не получен

   • Проверьте доступность URL

   • Убедитесь, что endpoint принимает POST запросы

   • Проверьте логи на стороне API

2. Таймаут webhook

   • Сократите время обработки в обработчике

   • Используйте асинхронную обработку для тяжелых операций

3. Ошибки парсинга JSON

   • Проверьте корректность обработки JSON в обработчике

   • Убедитесь в правильной настройке Content-Type