> For the complete documentation index, see [llms.txt](https://visaver.gitbook.io/visaver-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://visaver.gitbook.io/visaver-api/dokumentaciya/webhook-uvedomleniya.md).

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

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

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

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

```json
{
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "job_state": "done",
    "requested_actions": ["transcript", "summary", "quiz", "timecodes", "semantic_search", "multimodal_search"],
    "transcript": {
        "transcript_id": "transcript-uuid",
        "external_id": "external-uuid",
        "cues": [
            {
                "text": "Привет, добро пожаловать на наш канал",
                "start": 0.0,
                "duration_s": 5.5,
                "speaker": "Спикер 1"
            }
        ],
        "full_text": "Привет, добро пожаловать на наш канал. Сегодня мы расскажем..."
    },
    "summary": {
        "summary_id": "summary-uuid",
        "external_id": "external-uuid",
        "html": "<h1>Краткое изложение</h1><p>В данном видео рассматриваются...</p>"
    },
    "quiz": {
        "quiz_id": "quiz-uuid",
        "external_id": "external-uuid",
        "data": [
            {
                "quiz": {
                    "question": "О чем рассказывается в видео?",
                    "correct_answer": "О программировании",
                    "wrong_answers": ["О кулинарии", "О путешествиях", "О спорте"]
                },
                "chapter": {"start": 0.0}
            }
        ]
    },
    "timecodes": {
        "timecodes_id": "timecodes-uuid",
        "external_id": "external-uuid",
        "timecodes": [
            {
                "start": 0.0,
                "title": "Введение",
                "text": "Приветствие и обзор темы"
            }
        ]
    },
    "semantic_search": {
        "semantic_search_id": "semantic-search-uuid",
        "external_id": "external-uuid",
        "status": "done"
    },
    "multimodal_search": {
        "multimodal_search_id": "multimodal-search-uuid",
        "external_id": "external-uuid",
        "status": "done"
    }
}
```

В уведомление включаются только готовые продукты. Кадры (`frames`) в webhook не передаются — их список доступен через `GET /jobs/{job_id}/frames/`.

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

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

* `job_id` — UUID завершенной задачи
* `job_state` — статус задачи (`done` или `failed`)
* `requested_actions` — список запрошенных действий обработки
* `webhook_url` — URL, на который отправлен webhook

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

Каждый продукт включает свой UUID, `external_id` (UUID во внешней системе обработки) и содержимое. Продукт присутствует в уведомлении, только если он готов.

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

* `transcript_id` — UUID расшифровки
* `cues` — массив реплик: `text`, `start` (секунды), `duration_s` (секунды), `speaker`
* `full_text` — полный текст расшифровки

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

* `summary_id` — UUID краткого изложения
* `html` — HTML-содержимое краткого изложения

#### Quiz (квиз)

* `quiz_id` — UUID квиза
* `data` — массив элементов `{quiz: {question, correct_answer, wrong_answers}, chapter: {start}}`

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

* `timecodes_id` — UUID временных меток
* `timecodes` — массив меток: `start` (секунды), `title`, `text`

#### Semantic search / Multimodal search (индексы для поиска)

* `semantic_search_id` / `multimodal_search_id` — UUID записи
* `status` — `done`; означает, что индекс готов и можно выполнять запросы через `POST /semantic_search/` / `POST /multimodal_search/`

#### Frames (кадры)

В webhook не передаются; список кадров доступен через `GET /jobs/{job_id}/frames/`.

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

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

{% stepper %}
{% step %}

## Принимайте POST-запросы

Endpoint должен принимать POST-запросы с `Content-Type: application/json`.
{% endstep %}

{% step %}

## Возвращайте HTTP 200

Возвращайте HTTP 200 для подтверждения получения.
{% endstep %}

{% step %}

## Обрабатывайте запросы быстро

Рекомендуемое время обработки — менее 10 секунд.
{% endstep %}

{% step %}

## Обеспечьте доступность endpoint

Endpoint должен быть доступен по HTTP/HTTPS.
{% endstep %}
{% endstepper %}

### Пример обработчика (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`.

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

{% stepper %}
{% step %}

## Проверка источника

Рекомендуется проверять IP-адрес отправителя.
{% endstep %}

{% step %}

## Таймауты

Настройте разумные таймауты для обработки.
{% endstep %}

{% step %}

## Валидация

Всегда валидируйте входящие данные.
{% endstep %}
{% endstepper %}

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

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

<details>

<summary>Webhook не получен</summary>

* Проверьте доступность URL.
* Убедитесь, что endpoint принимает POST-запросы.
* Проверьте логи на стороне API.

</details>

<details>

<summary>Таймаут webhook</summary>

* Сократите время обработки в обработчике.
* Используйте асинхронную обработку для тяжелых операций.

</details>

<details>

<summary>Ошибки парсинга JSON</summary>

* Проверьте корректность обработки JSON в обработчике.
* Убедитесь в правильной настройке Content-Type.

</details>