Webhooks Vision AI: real-time уведомления и live интеграция

Вы создали систему, где после загрузки фото товара автоматически генерируется визуализация, отправляется в Shopify и уведомляет менеджера в Slack.

Как это работает? Webhooks.

Webhook = когда Vision AI завершает генерацию, она отправляет вам push-уведомление (webhook) с результатом. Вы не опрашиваете Vision AI ("готово ли?"), а Vision AI сама вам говорит ("готово!").

Что такое webhooks и зачем они нужны

Без webhooks: Polling (опрашивание)

```

1. 1Вы отправляете запрос генерации

POST /api/generate → Status: processing

1. 1Вы САМИ постоянно спрашиваете

GET /api/status → Status: still processing (повторяете каждые 2 секунды)

1. 1Когда результат готов

GET /api/status → Status: done, Images: [...]

Проблема: Много ненужных запросов, задержки, нагрузка на сервер ```

С webhooks: Push-уведомления

```

1. 1Вы отправляете запрос генерации

POST /api/generate → ID: gen_123

1. 1Vision AI обрабатывает (вы ничего не делаете)

1. 1Когда результат готов, Vision AI

отправляет ВАМ webhook: POST https://your-server.com/webhook Body: { "event": "generation.completed", "generation_id": "gen_123", "images": [...] }

Преимущество: Real-time, эффективно, минимум нагрузки ```

Метрики улучшения

``` Polling approach:

• Задержка до результата: 5–10 сек (ждете, пока спросите)
• API calls: 100K запросов в день × 10 проверок = 1M лишних запросов/день
• Нагрузка: высокая

Webhook approach:

• Задержка до результата: < 1 сек (получаете сразу)
• API calls: только необходимые запросы
• Нагрузка: минимальная

```

Event types: какие события есть

Vision AI отправляет webhook уведомления для этих событий:

1. `generation.created`

Когда: Проект и запрос генерации только что созданы

```json { "event": "generation.created", "generation_id": "gen_123", "project_id": "proj_456", "created_at": "2026-04-13T10:00:00Z", "style": "modern", "quantity": 3 } ```

2. `generation.started`

Когда: Начата обработка (попала в очередь)

```json { "event": "generation.started", "generation_id": "gen_123", "started_at": "2026-04-13T10:00:05Z", "queue_position": 15, "estimated_time": 45 // секунды } ```

3. `generation.processing`

Когда: Идет генерация AI моделью

```json { "event": "generation.processing", "generation_id": "gen_123", "progress": 45, // процент "current_step": "rendering", "elapsed_time": 20 // секунды } ```

4. `generation.completed`

Когда: Генерация завершена успешно

```json { "event": "generation.completed", "generation_id": "gen_123", "project_id": "proj_456", "completed_at": "2026-04-13T10:00:45Z", "duration_seconds": 40, "images": [ { "id": "img_1001", "url": "https://cdn.vision-ai.org/...", "style": "modern", "width": 1200, "height": 800 }, { "id": "img_1002", "url": "https://cdn.vision-ai.org/...", "style": "classic", ... }, ... ], "metadata": { "prompt": "Living room with sofa", "model_version": "v2.5" } } ```

5. `generation.failed`

Когда: Произошла ошибка обработки

```json { "event": "generation.failed", "generation_id": "gen_123", "failed_at": "2026-04-13T10:00:45Z", "error_code": "INVALID_IMAGE_FORMAT", "error_message": "Uploaded image is not a valid JPEG or PNG", "retry_count": 0 } ```

Структура webhook payload

Базовая структура

```json { // Метаинформация события "event": "generation.completed", "webhook_id": "wh_789xyz", "delivery_attempt": 1, "timestamp": "2026-04-13T10:00:45Z",

// Сигнатура для безопасности (см. ниже) "signature": "sha256=...",

// Данные события "data": { "generation_id": "gen_123", "project_id": "proj_456", "status": "completed", ...event specific fields... } } ```

Типичный размер payload

• Простое событие (created, started): ~200 bytes
• Сложное событие (completed с 5 изображениями): ~2–5 KB
• Максимальный payload: 5 MB

Безопасность: HMAC signing

Почему HMAC важна

Webhook отправляется на ваш публичный URL. Как убедиться, что это реально от Vision AI, а не от хакера?

Ответ: HMAC подпись

Как работает HMAC

``` Vision AI знает ваш webhook secret: "secret_abc123xyz"

Перед отправкой webhook:

1. 1Берет webhook body (JSON)
2. 2Подписывает его с secret: HMAC-SHA256(body, secret)
3. 3Получает подпись: "sha256_abc123xyz789"
4. 4Отправляет webhook с этой подписью в header

Вы получаете webhook:

1. 1Извлекаете подпись из header
2. 2Вычисляете свою подпись: HMAC-SHA256(тот же body, ваш secret)
3. 3Сравниваете подписи
4. 4Если совпадают → это реально от Vision AI
5. 5Если не совпадают → это хакер или ошибка

```

Проверка HMAC в Python

```python import hmac import hashlib from flask import Flask, request, jsonify

app = Flask(__name__) WEBHOOK_SECRET = 'your_webhook_secret_from_vision_ai_dashboard'

@app.route('/webhook', methods=['POST']) def handle_webhook(): # Получить сигнатуру из header signature = request.headers.get('X-Vision-AI-Signature') body = request.get_data()

# Вычислить ожидаемую сигнатуру expected_signature = 'sha256=' + hmac.new( WEBHOOK_SECRET.encode(), body, hashlib.sha256 ).hexdigest()

# Проверить if not hmac.compare_digest(signature, expected_signature): return {'error': 'Invalid signature'}, 401

# Сигнатура валидна, обрабатываем webhook data = request.json event = data['event']

if event == 'generation.completed': process_completed(data) elif event == 'generation.failed': process_failed(data)

return {'ok': True}, 200

def process_completed(data): # Сохранить результаты в БД generation_id = data['generation_id'] images = data['images'] # ... ```

Проверка HMAC в Node.js

```javascript const crypto = require('crypto'); const express = require('express'); const app = express();

const WEBHOOK_SECRET = 'your_webhook_secret_from_vision_ai_dashboard';

app.post('/webhook', (req, res) => { const signature = req.headers['x-vision-ai-signature']; const body = req.rawBody; // Убедитесь, что сохраняли raw body

// Вычислить сигнатуру const expectedSignature = 'sha256=' + crypto .createHmac('sha256', WEBHOOK_SECRET) .update(body) .digest('hex');

// Проверить if (signature !== expectedSignature) { return res.status(401).json({ error: 'Invalid signature' }); }

// Обработать webhook const data = JSON.parse(body); handleWebhook(data);

res.json({ ok: true }); });

function handleWebhook(data) { const { event, data: eventData } = data;

if (event === 'generation.completed') { // Сохранить результаты в БД console.log('Generation completed:', eventData); } }

app.listen(3000); ```

Как настроить webhooks

Шаг 1: Создать webhook endpoint у себя

На вашем сервере создайте endpoint, который будет получать webhooks:

```python # Python Flask @app.route('/api/webhooks/vision-ai', methods=['POST']) def vision_ai_webhook(): # ... обработка (см. выше с HMAC) return {'ok': True}, 200 ```

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

• HTTP(S) метод: POST
• Должен возвращать 200 ОК в течение 30 секунд
• Должен быть публичный (Vision AI должна иметь доступ)

Шаг 2: Получить webhook secret

На dashboard Vision AI:

1. 1Перейти в Settings → Webhooks
2. 2Нажать "Create webhook endpoint"
3. 3Вставить URL вашего endpoint: `https://your-domain.com/api/webhooks/vision-ai`
4. 4Выбрать события: `generation.completed`, `generation.failed`
5. 5Нажать "Create"
6. 6Скопировать webhook secret (используется для HMAC)

Шаг 3: Добавить secret в ваше приложение

```bash # В .env файле VISION_AI_WEBHOOK_SECRET=whk_1234567890abcdef ```

```python # В приложении import os WEBHOOK_SECRET = os.getenv('VISION_AI_WEBHOOK_SECRET') ```

Шаг 4: Тестировать

На Vision AI dashboard:

1. 1Нажать "Send test webhook"
2. 2Выбрать тип события
3. 3Система отправит пробный webhook на ваш endpoint
4. 4Проверить логи вашего сервера

```bash # Логи должны показать: Received webhook: generation.completed Signature verified: ✓ Data processed: ✓ ```

Обработка ошибок и retries

Что делать, если webhook не прошел

Сценарий: Ваш сервер был down, когда Vision AI отправляла webhook.

Vision AI автоматически повторит отправку:

``` Попытка 1: T+0min → ошибка Попытка 2: T+1min → ошибка Попытка 3: T+5min → успех ✓ ```

Максимум попыток: 10 Интервал: exponential backoff (1, 5, 25, 60+ минут)

Идемпотентность

Важно обрабатывать одно событие несколько раз без побочных эффектов:

```python def process_completed(data): generation_id = data['generation_id'] images = data['images']

# Проверить, не обработано ли уже existing = db.query(Generation).filter( Generation.id == generation_id ).first()

if existing: # Уже обработано, skip return

# Первая обработка db.create(Generation, { 'id': generation_id, 'images': images, 'processed_at': now() }) ```

Логирование webhook доставки

На Vision AI dashboard можно видеть все доставки:

``` Webhook Log: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Delivery #3 → 2026-04-13 10:00:45 Status: ✓ Success Response time: 245 ms Response code: 200

Delivery #2 → 2026-04-13 10:00:10 Status: ✗ Failed (timeout)

Delivery #1 → 2026-04-13 10:00:00 Status: ✗ Failed (connection refused) ```

Кейсы использования

Кейс 1: E-commerce Shopify + Slack уведомления

``` Webhook event: generation.completed ↓ Your server receives it ↓ Uploads image to Shopify product ↓ Sends message to Slack: "✅ Product visualization ready" ↓ Marketing team sees it → approves → publishes ```

ROI: Автоматизирует workflow, экономит 1–2 часа/день

Кейс 2: CRM (HubSpot) автоматическое обновление

``` Webhook event: generation.completed ↓ Your server extracts images ↓ Updates Deal in HubSpot with images ↓ Sends email to prospect: "Посмотрите ваш дизайн!" ```

ROI: Ускоряет sales cycle на 30–50%