Видео API

Webhook для генерации видео API: безопасный обработчик

Видео генерируется дольше HTTP-запроса, поэтому типичный жизненный цикл состоит из отправки задачи, сохранения task_id и получения результата через polling или callback. Webhook уменьшает число опросов, но лишь тогда, когда обработчик проверяет подлинность события, не создаёт дубли и не выдаёт результат раньше времени.

Опубликовано 12 августа 2026 · 12 минут чтения · Ключевой запрос: webhook для генерации видео API

Короткий ответ

Создайте задачу на сервере, сохраните свой ID и внешний task_id, затем принимайте callback на выделенном HTTPS endpoint. До изменения статуса проверьте подпись по правилам конкретного API, временную метку, event ID и соответствие известной задаче. Уникально сохраните событие, верните быстрый 2xx и передайте скачивание, проверку и выдачу результата фоновому worker.

Что webhook решает, а что не решает

Callback сообщает, что поставщик считает событие готовым к обработке. Он не отменяет хранение статуса и не делает доставку ровно один раз. Сеть способна повторить запрос, отправить события не по порядку или доставить одно событие после вашего тайм-аута. Поэтому приложение строят для режима «как минимум один раз»: повтор идентичного event ID безопасен, а более старый статус не перезаписывает финальный.

Webhook также не подтверждает безусловную доступность конкретной модели и не заменяет проверку прав на контент. Не называйте стороннюю интеграцию официальным endpoint производителя. До показа ролика пользователю проверьте собственную задачу, статус, правила хранения и URL, предоставленный в подтверждённом событии. Если сервис поддерживает polling, его можно оставить как ограниченный резервный механизм для незавершённых задач, не как способ обойти лимиты.

Минимальная модель состояния

Для каждой генерации храните внутренний ID, пользователя или проект, внешний task ID, состояние, время и безопасные технические поля. Полезны статусы queued, running, succeeded, failed, cancel_requested и unknown. Переходы должны быть явными: событие running не может вернуть задачу из succeeded назад, а повтор succeeded не создаёт новую запись.

Отдельно храните обработанные event ID с уникальным индексом и временем истечения. Это простая защита от повторной доставки. Не записывайте в БД заголовки с секретами, полный payload без необходимости или временный URL результата, если он содержит чувствительные параметры. Для отладки достаточно хеша тела, event ID, task ID, времени и результата проверки подписи.

Проверка подписи: порядок важнее алгоритма

Каждый сервис публикует свой способ подписи: секрет, заголовок, сырой body, timestamp и допустимое окно времени. Не заменяйте его выдуманным стандартом. Сохраните необработанное тело запроса, извлеките нужные заголовки, проверьте свежесть timestamp, вычислите HMAC либо выполните иной документированный шаг и сравните значение функцией постоянного времени. Только потом разбирайте JSON и меняйте состояние задачи.

Секрет webhook — это не API Key пользователя и не параметр URL. Его хранят в защищённой серверной переменной, меняют по процедуре ротации и не вставляют в пример или тикет. Если провайдер не предлагает подпись, выберите дополнительные контролируемые меры из его документации: например, allowlist IP при стабильном опубликованном диапазоне. Не полагайтесь лишь на IP и не называйте такую схему полной аутентификацией.

Пример Express-обработчика

Этот пример показывает каркас Node.js 20+ для HMAC-SHA256. Названия заголовков и точная строка подписи являются примером: замените их только на подтверждённые в документации RussiaAPI или используемого endpoint правила. Маршрут должен принимать сырой body; иначе подпись после JSON-парсинга может не совпасть.

import crypto from 'node:crypto';
import express from 'express';
const app = express();

app.post('/webhooks/video', express.raw({ type: 'application/json' }), async (req, res) => {
  const received = req.header('x-webhook-signature') || '';
  const expected = crypto.createHmac('sha256', process.env.RUSSIAAPI_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  const inserted = await events.insertIfAbsent(event.id, event.task_id);
  if (!inserted) return res.sendStatus(204);
  await jobs.enqueue({ eventId: event.id, taskId: event.task_id });
  return res.sendStatus(202);
});

После 202 отдельный worker читает событие, находит известную задачу, проверяет допустимый переход статуса и только затем получает результат. Не скачивайте большой файл прямо в callback: долгий ответ повышает риск повторной доставки. Если API присылает ссылку, валидируйте её по правилам сервиса и не передавайте её напрямую в браузер, пока не проверены права пользователя и срок доступа.

Как совместить webhook и polling

Сначала используйте callback как основной сигнал. Если задача остаётся pending дольше согласованного времени, очередь может осторожно запросить статус по внешнему task ID собственным ключом RussiaAPI. Частоту polling выбирают консервативно, с backoff и джиттером, чтобы не создавать лишнюю нагрузку. Ошибка 429 — сигнал замедлиться и проверить лимиты, а не начать использовать чужие ключи или бесконечные параллельные запросы.

Polling и callback должны писать в одну модель состояния. Сравнивайте время и допустимость перехода, чтобы поздний callback не затёр свежую финальную проверку. Для защиты от повторов используйте тот же подход, что и для других действий: idempotency key и дедупликация операций дают приложению один источник правды.

Безопасность контента и наблюдаемость

Видео-задача может содержать изображения, текст, голос, лицо или бренд. До отправки определите, кто имеет право использовать входные данные и как долго они хранятся. Не обещайте, что генерация допустима в любой юрисдикции или для любого сюжета. Ограничьте доступ к результату авторизованным пользователем, удаляйте временные объекты по политике хранения и не пишите приватные URL в публичные логи.

Для поддержки соберите event ID, внутренний ID, task ID, дату, код ответа и обезличенный текст ошибки. Метрики полезнее сплошного payload: отслеживайте время от создания до callback, долю повторных событий, ошибки подписи, число задач в unknown и время выдачи пользователю. С этим набором можно расследовать проблему без просьбы прислать API Key или исходный медиаматериал.

Проверьте перед запуском

• HTTPS endpoint доступен извне, но не раскрывает диагностические данные в ответе.
• Подпись и timestamp проверяются по актуальной документации конкретного endpoint.
• У event ID есть уникальное ограничение, а task ID связан с известной задачей.
• Тяжёлая работа вынесена в очередь; callback отвечает быстро.
• Права на контент, сроки хранения и доступ к результату определены продуктом.

FAQ

Читайте также

• Асинхронная генерация видео: task ID и polling
• Повторные запросы без дублей
• 429 API: backoff и лимиты
• Документы RussiaAPI