Вебхуки в разделе «Видео-аватары»: уведомление на свой сервер, когда ролик готов
Вебхуки в разделе «Видео-аватары» — это способ узнать, что ролик готов, без ручного обновления страницы: как только видео досчиталось, на адрес вашего сервера уходит POST-запрос, и ваш сервер сам решает, что делать дальше — записать ссылку в базу, отдать файл клиенту или запустить следующий шаг. Вкладка нужна тем, кто делает видео пачками или встраивает генерацию аватаров в свой продукт: вместо бесконечных проверок «готово или ещё нет» приходит одно короткое уведомление ровно в нужный момент.
Зачем это вообще нужно
Рендер видео — не мгновенная операция, и ждать его в открытой вкладке бессмысленно. По замерам платформы от 07.09.2026 пятисекундный ролик Kling 3.0 в 1080p считается в среднем 115 секунд, а в 95% случаев укладывается в 165. У Sora 2 то же задание занимает в среднем около 145 секунд. Если проверять статус каждые несколько секунд, за один ролик набегают десятки пустых запросов; вебхук приходит один раз — когда результат действительно появился.
Объём тоже говорит сам за себя. По журналу генераций платформы за 30 дней (3 сентября — 2 октября 2026) стартовало 3 292 задачи на видео, из них 2 369 завершились успешно. Ролики считаются в фоне и заканчиваются в разное время — вручную это не отследить, а аккуратный обработчик уведомлений решает задачу сам.
Что даёт вкладка «Вебхуки»
Здесь всё про доставку уведомлений, без магии. Вы регистрируете адрес, выбираете, на какие события подписаться, и получаете подписной секрет. Список зарегистрированных эндпоинтов хранится тут же: видно адрес, выбранные события, статус и стоит ли на эндпоинте секрет. Секрет можно перевыпустить (старый сразу перестанет работать) или удалить эндпоинт целиком.
Событие приходит только по вашим роликам: чужое видео наружу не уйдёт, даже если оно считалось в тот же момент. Есть и журнал доставленных событий — по нему удобно проверить, что до вашего сервера действительно что-то дошло.
Как начать — по шагам
- Откройте раздел «Видео-аватары» и панель вебхуков по прямому адресу /ru/avatars?tab=webhooks.
- Войдите в аккаунт: гостю настройка недоступна, при нажатии откроется окно входа.
- В поле «Адрес эндпоинта» укажите публичный HTTPS-адрес своего сервера, например https://example.com/avatar-webhook. HTTP не подойдёт — доставка и подпись рассчитаны на защищённый канал.
- Отметьте нужные события. Если не выбрать ничего, подписка будет сразу на все события.
- Нажмите «Добавить эндпоинт». Сразу после создания покажется подписной секрет — скопируйте и сохраните его у себя: повторно он не отображается.
- Если своего сервера пока нет, нажмите «Подставить наш приёмник» — тогда уведомления будут копиться в журнале доставленных событий прямо во вкладке.
Как убедиться, что запрос от нас, а не подделка
К каждому запросу прилагается заголовок signature — это HMAC-SHA256, посчитанный от сырого тела запроса вашим секретом. На своей стороне посчитайте ту же подпись и сравните: не сошлось — запрос отбрасываем. Наш приёмник делает ровно так и отвечает 401 на неверную подпись. Секрет держите на сервере, в переменных окружения, а не в клиентском коде.
Что приходит в запросе
Тело — обычный JSON с типом события и данными сущности. Например, у готового видео это событие avatar_video.success с идентификатором ролика внутри. Полный список доступных типов событий показан во вкладке: его можно перебрать и оставить только то, что реально нужно вашему сервису.
Сколько это стоит
Регистрация эндпоинта, перевыпуск секрета, удаление и журнал событий токены не списывают — это настройка уведомлений, а не генерация. Токены расходуются только на само видео: цена в токенах видна до запуска, а если задача не удалась, списанное возвращается. Подписки нет: новым пользователям начисляются стартовые токены на первые пробы.
С чем сочетать
- «Пакетные задачи» — запуск десятков роликов одним заданием; вебхук избавит от ручного контроля готовности.
- «Медиатека» — хранение исходников и готовых файлов.
- «Перевод видео» и «Нарезка клипов» — следующие шаги после генерации.
Частые вопросы
Какой адрес подходит для вебхука?
Только публичный HTTPS. Локальные адреса и HTTP не принимаются: уведомление должно идти по защищённому каналу, а ваш сервер — быть доступен извне.
Можно ли получать уведомления, если своего сервера нет?
Да. Нажмите «Подставить наш приёмник» — события будут копиться в журнале «Доставленные события» во вкладке, их можно смотреть без своего бэкенда.
Что делать, если подпись не сходится?
Проверьте, что вы считаете HMAC-SHA256 именно от сырого тела запроса (а не от разобранного JSON) и что используете актуальный секрет: после перевыпуска старый сразу перестаёт работать.
Это платно?
Настройка вебхуков токены не списывает. Токены тратятся только на генерацию видео — их цена видна до запуска; подписки нет, новым пользователям начисляются стартовые токены.