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

Вступ до вебхуків

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

Механіка проста й однакова в усіх провайдерів. Сервер-отримувач перевіряє запит (в ідеалі — криптографічний підпис), швидко відповідає статусом 2xx і ставить важку роботу в чергу для фонової обробки. Усе інше — назви подій, структура payload, поведінка повторних спроб — залежить від вендора, тому розуміти патерн важливіше, ніж запам'ятовувати поля будь-якого окремого провайдера.

Де налаштовуються URL-адреси вебхуків

Налаштування завжди залежить від провайдера. Ви реєструєте свою публічну HTTPS-точку в панелі керування або API саме того вендора — сервісу кодування, live-платформи, платіжного провайдера тощо. Типовий порядок такий: вставити свою callback-адресу, обрати типи подій, які хочете отримувати, і надійно зберегти секрет для підпису, який вам видадуть. Універсального «екрана вебхуків», що охоплював би всіх вендорів, не існує; ви дотримуєтеся документації того продукту, з яким справді інтегруєтеся, бо точне розташування й термінологія щоразу різні.

DCAST і продукти для розробників

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

Інтеграції Partner і API — документація та інструменти для розробників або поверхні Pro/partner — це місце, де належать зворотні виклики, підписані події та пов'язані пункти дорожньої карти; їх описано в офіційній документації 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 як сповіщення, а не як джерело істини. Для всього важливого за ID із 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-парсер уже повторно серіалізував тіло, байти можуть відрізнятися, і підпис ніколи не збігатиметься, тож якщо провайдер цього вимагає, зберігайте сире тіло до парсингу.

Обробка помилок і повторні спроби

Реалізуйте ідемпотентність: зберігайте ID кожної опрацьованої події й пропускайте дублікати, бо провайдери будуть доставляти одну й ту саму подію більше ніж один раз під час збоїв у мережі. Повертайте статус 2xx лише після того, як надійно прийняли подію — зазвичай після запису в довготривалу чергу, а не після завершення самої роботи. Потім обробляйте довготривалі завдання асинхронно, щоб відправник не отримав тайм-аут. Якщо виконувати важку роботу всередині обробника й відповідати надто довго, провайдер вирішить, що сталася помилка, повторить запит, і ви в кінці кінців оброблятимете одну й ту саму подію знову і знову.

Найкращі практики

1. Безпека: завжди використовуйте HTTPS, перевіряйте підписи кожного запиту й відхиляйте все, що не пройшло перевірку, відповіддю 401 або 403.
2. Ідемпотентність: виходьте з того, що доставка може дублюватися, і дедуплікуйте за ID події, щоб повторна доставка ніколи не призводила до подвійного списання, подвійної публікації чи подвійного сповіщення.
3. Швидке підтвердження: відповідайте швидко статусом 2xx, а справжню роботу виконуйте у фоновій черзі.
4. Моніторинг: логуйте кожну доставку й збій, налаштуйте сповіщення про сплески відповідей не 2xx і ведіть чергу невдалих повідомлень (dead-letter queue) для подій, які не вдалося обробити.

Локальне тестування вебхуків

Оскільки вебхуку потрібна публічно доступна URL-адреса, для тестування на ноутбуці потрібен тунель. Інструменти на кшталт ngrok відкривають ваш локальний сервер на тимчасовій публічній HTTPS-адресі, щоб провайдер міг звернутися до http://localhost:3000 під час розробки. Багато провайдерів також пропонують кнопку «надіслати тестову подію» та журнал доставок із кожною спробою й кодом відповіді, який ви повернули — користуйтеся обома, щоб переконатися, що ваша точка перевіряє підписи, швидко повертає 2xx і правильно обробляє payload, перш ніж покладатися на неї в продакшені.

Висновок

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

Наступні кроки та ресурси

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