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

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

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

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

```json
{
    "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)

```python
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/` для отладки:

```bash
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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://visaver.gitbook.io/visaver-api/dokumentaciya/webhook-uvedomleniya.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.