Видео Вещание

Вебхуки в видеопроцессах: автоматизация вашего пайплайна

Вебхуки для автоматизации видео: как они работают, универсальные payload и примеры на Node.js. Уточняется, что в публичном кабинете автора dcast.tv нет универсального раздела настройки вебхуков: опирайтесь на реальную документацию поставщиков и материалы Partner API там, где это применимо.

dcast Team
8 мин чтения
Поделиться:
Вебхуки в видеопроцессах: автоматизация вашего пайплайна
On this page

Введение в вебхуки

Вебхуки позволяют одной системе уведомить другую о каком-либо событии, отправив HTTP-запрос на подконтрольный вам URL. Вместо того чтобы ваше приложение постоянно опрашивало API и спрашивало «видео уже готово?», провайдер присылает сообщение в тот самый момент, когда событие происходит. В видеопроцессах это основа автоматизации: завершение транскодирования, события жизненного цикла трансляции, доступность записи и завершение загрузки могут запускать следующий шаг вашего пайплайна без человека, который следит за панелью управления.

Загружайте, вещайте и продавайте видео. Начните на бесплатном тарифе — без карты.

Начать бесплатно

Механика проста и у разных провайдеров одинакова. Принимающий сервер проверяет запрос (в идеале — проверяя криптографическую подпись), быстро отвечает статусом 2xx и ставит тяжёлую работу в очередь на фоновую обработку. Всё остальное — названия событий, форма payload, поведение при повторных попытках — зависит от поставщика, поэтому понимать шаблон важнее, чем запоминать поля какого-то одного провайдера.

Где настраиваются URL вебхуков

Настройка всегда зависит от конкретного провайдера. Вы регистрируете свой публичный HTTPS-эндпоинт в кабинете или API именно того поставщика — сервиса кодирования, платформы прямых трансляций, платёжного провайдера и так далее. Обычный порядок такой: вставьте свой callback-URL, выберите типы событий, которые хотите получать, и надёжно сохраните секрет для подписи, который вам выдадут. Универсального «экрана вебхуков», общего для всех поставщиков, не существует; следуйте документации того продукта, с которым вы действительно интегрируетесь, потому что точное расположение настроек и терминология каждый раз разные.

DCAST и продукты для разработчиков

Публичный кабинет автора на dcast.tv не содержит универсальной страницы настроек «Вебхуки», где можно добавить произвольные URL для событий вроде «транскодирование завершено» или «трансляция началась».

Интеграции для партнёров и API — документация и инструменты, рассчитанные на разработчиков или партнёрские разделы Pro, — это то место, где описываются обратные вызовы, подписанные события и связанные пункты дорожной карты; они описаны в официальной документации Partner API и для разработчиков, а не в выдуманном процессе через пользовательский кабинет. Если сомневаетесь, доверяйте официальной документации, а не учебнику, включая это руководство.

Типичные события вебхуков в видеопроцессах

Точные названия различаются у разных провайдеров, но категории событий удивительно единообразны во всей отрасли:

  • Транскодирование или кодирование завершено — материал готов к воспроизведению или к следующему шагу пайплайна (миниатюры, субтитры, публикация).
  • Трансляция началась / завершилась — жизненный цикл прямого эфира, полезный для аналитики, уведомлений и запуска записи.
  • Запись готова — повтор или VOD-версия прямой трансляции теперь доступна.
  • Загрузка завершена — приём файла завершён, и исходный файл надёжно сохранён.

В продуманном пайплайне эти события выстраиваются в цепочку: upload completed запускает транскодирование, transcoding finished запускает создание миниатюр и помечает материал как готовый к публикации, а recording ready уведомляет подписчиков, что появился повтор. Каждое событие выполняет одну задачу и передаёт эстафету следующему.

Что нужно знать о payload вебхуков

Payload почти всегда — JSON. Всегда читайте реальную схему вашего провайдера, потому что имена полей и вложенность различаются: пример ниже универсальный и приведён только для иллюстрации:

{
  "event": "transcoding_finished",
  "video_id": "12345",
  "status": "success",
  "filename": "example_video.mp4",
  "timestamp": "2023-10-05T12:00:00Z"
}

Две привычки избавят вас от настоящей боли. Во-первых, никогда не считайте, что поле существует: проверяйте его наличие, прежде чем использовать, ведь со временем провайдеры добавляют и переименовывают поля. Во-вторых, относитесь к payload как к уведомлению, а не как к источнику истины. Для всего важного используйте идентификатор из payload, чтобы получить достоверную запись через API провайдера, а не слепо доверять телу вебхука, ведь payload можно подделать или воспроизвести повторно.

Обработка вебхуков в Node.js

Простой обработчик

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const port = 3000;

app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  console.log('Received webhook event: ' + payload.event);
  res.status(200).send('Webhook received');
});

app.listen(port, () => {
  console.log('Webhook server listening on port ' + port);
});

Пример: ветвление по типу события

app.post('/webhook', (req, res) => {
  const payload = req.body;
  if (payload.event === 'transcoding_finished') {
    console.log('Transcoding finished for video ' + payload.video_id);
  }
  res.status(200).send('Webhook received');
});

Проверка подписей

Самый важный шаг безопасности — убедиться, что запрос действительно пришёл от вашего провайдера и не был подделан. Большинство поставщиков подписывают каждый запрос с помощью HMAC от необработанного тела запроса, используя ваш общий секрет, и отправляют результат в заголовке. Ваша задача — пересчитать эту подпись и сравнить её за постоянное время:

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  // constant-time compare avoids leaking timing information
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Обратите внимание: для проверки подписи обычно нужно необработанное тело запроса в точности в том виде, в каком оно получено. Если ваш JSON-парсер уже пересериализовал тело, байты могут отличаться, и подпись никогда не совпадёт, поэтому, если провайдер этого требует, сохраняйте необработанное тело до разбора.

Обработка ошибок и повторные попытки

Реализуйте идемпотентность: сохраняйте идентификатор каждого обработанного события и пропускайте дубликаты, потому что провайдеры будут доставлять одно и то же событие больше одного раза при сетевых сбоях. Возвращайте статус 2xx только после того, как вы безопасно приняли событие — обычно после записи в надёжную очередь, а не после завершения самой работы. Затем обрабатывайте длительные задачи асинхронно, чтобы отправитель не получил таймаут. Если вы выполняете тяжёлую работу прямо в обработчике и отвечаете слишком долго, провайдер решит, что произошёл сбой, и повторит отправку, а вы будете обрабатывать одно и то же событие снова и снова.

Лучшие практики

  1. Безопасность: всегда используйте HTTPS, проверяйте подписи в каждом запросе и отклоняйте всё, что не прошло проверку, ответом 401 или 403.
  2. Идемпотентность: исходите из того, что возможны повторные доставки, и дедуплицируйте по идентификатору события, чтобы повторная доставка никогда не приводила к двойному списанию, двойной публикации или двойному уведомлению.
  3. Быстрое подтверждение: отвечайте быстро статусом 2xx, а настоящую работу выполняйте в фоновой очереди.
  4. Мониторинг: логируйте каждую доставку и сбой, настройте оповещения о всплесках ответов не из семейства 2xx и держите очередь недоставленных сообщений для событий, которые не удалось обработать.

Локальное тестирование вебхуков

Поскольку вебхуку нужен публично доступный URL, для тестирования на ноутбуке требуется туннель. Такие инструменты, как ngrok, открывают ваш локальный сервер на временном публичном HTTPS-адресе, чтобы провайдер мог достучаться до http://localhost:3000 во время разработки. Многие провайдеры также предлагают кнопку «отправить тестовое событие» и журнал доставок, где видна каждая попытка и код ответа, который вы вернули. Используйте и то и другое, чтобы убедиться, что ваш эндпоинт проверяет подписи, быстро возвращает 2xx и правильно обрабатывает payload, прежде чем полагаться на него в продакшене.

Заключение

Вебхуки — стандартный и надёжный способ автоматизировать видеопроцессы, но только если используемая вами платформа действительно их поддерживает и только если вы обрабатываете их безопасно и идемпотентно. Сверяйте поведение с актуальной документацией продукта и проверяйте подписи в каждом запросе. Один раз правильно выстройте шаблон, и та же дисциплина пригодится при интеграции с любым провайдером.

Следующие шаги и ресурсы

  • Используйте официальную документацию вашего поставщика кодирования или стриминга, чтобы узнать типы событий, формат payload и особенности проверки подписи.
  • Для DCAST опирайтесь на опубликованные материалы Partner API / для разработчиков, чтобы понять рамки интеграции; не предполагайте, что на dcast.tv есть интерфейс вебхуков в пользовательском кабинете.

Часто задаваемые вопросы

Что такое вебхуки и как они работают в видеопроцессах?

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

Как настроить вебхуки для видеопровайдера?

Процесс всегда зависит от конкретного провайдера. Вы регистрируете свой публичный HTTPS-эндпоинт в кабинете или API этого поставщика, выбираете нужные типы событий и сохраняете секрет для подписи, который он выдаёт. Универсального процесса нет, поэтому следуйте документации того продукта, с которым вы интегрируетесь. Что касается dcast.tv, опирайтесь на официальные материалы Partner API и для разработчиков, а не предполагайте, что в пользовательском кабинете есть экран настройки вебхуков.

Какие типичные события запускают вебхуки в видеопроцессах?

К распространённым событиям относятся «транскодирование завершено», «трансляция началась», «трансляция завершилась», «запись готова» и «загрузка завершена». Точные названия различаются у разных провайдеров, но эти категории покрывают большинство задач автоматизации.

Как защитить и проверить payload вебхуков?

Обслуживайте эндпоинт по HTTPS и проверяйте криптографическую подпись, которую провайдер присылает с каждым запросом, используя общий секрет и сравнение за постоянное время. Относитесь к payload как к уведомлению, а не как к источнику истины: используйте содержащиеся в нём идентификаторы, чтобы получить достоверную запись через API провайдера, прежде чем предпринимать какие-либо важные действия.

Как обрабатывать повторные или неудачные доставки вебхуков?

Сделайте обработчик идемпотентным: записывайте идентификатор каждого обработанного события и пропускайте повторы, ведь провайдеры повторяют отправку при любом ответе не из семейства 2xx или таймауте. Быстро подтверждайте получение ответом 2xx после безопасной постановки события в очередь, выполняйте тяжёлую работу асинхронно и держите очередь недоставленных сообщений (dead-letter queue) и мониторинг, чтобы неудачные доставки были видны и их можно было восстановить.

Документация API по этой теме

стримингпрямые трансляциивидеовебхукирабочие процессыавтоматизация видео
d

dcast Team

Профессионалы видеостриминга, которые помогают авторам добиваться успеха.

Начните свой видеобизнес сегодня

Загружайте, вещайте и продавайте видео. Начните на бесплатном тарифе — без карты.

Начать бесплатно