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

Знайомство з вебхуками

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

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

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

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

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

Публічний досвід творця на dcast.tv не включає загальної сторінки налаштувань «Вебхуки», де ви додаєте довільні URL для подій на кшталт «транскодування завершено» чи «трансляція розпочалася», попри те, що стверджують деякі застарілі SEO-чернетки. Не дотримуйтеся інструкцій, які кажуть користувачам увійти в дашборд dcast.tv і клікнути «ручну дію вебхука в дашборді» — споживчий продукт працює не так, і копіювання цих кроків призведе лише до плутанини. Партнерські та API-інтеграції — документація й інструментарій, орієнтовані на розробників чи Pro/партнерські поверхні — це те, де належать callback-и, підписані події та пов'язані пункти дорожньої карти, описані в офіційній Partner API та документації для розробників, а не у вигаданому споживчому флоу дашборда. Практичне правило: вважайте будь-який текст блогу, що обіцяє конкретний UI dcast.tv, застарілим, якщо він не відповідає поточній документації продукту. Коли сумніваєтеся, довіряйте офіційній документації, а не туторіалу, зокрема й цьому.

Поширені події вебхуків у відеоробочих процесах

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

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

Добре спроєктований конвеєр зчіплює їх: `upload completed` запускає транскодування, `transcoding finished` запускає генерацію прев'ю й позначає актив придатним до публікації, а `recording ready` сповіщає передплатників, що повтор існує. Кожна подія виконує одну роботу й передає естафету наступній.

Розуміння payload вебхуків

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

```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

Налаштування простого слухача

```javascript

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);

});

```

Приклад: розгалуження за типом події

```javascript

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-ом сирого тіла запиту за допомогою вашого спільного секрету й надсилають результат у заголовку. Ваше завдання — перерахувати цей підпис і порівняти його за сталий час:

```javascript

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 чергу для подій, які не змогли обробити.

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

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

Поширені запитання

Що таке вебхуки і як вони працюють у відеоробочих процесах?

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

Як налаштувати вебхуки для відеопровайдера?

Процес завжди специфічний для провайдера. Ви реєструєте свій публічний HTTPS-ендпоінт у дашборді чи API того вендора, обираєте типи подій, які вас цікавлять, і зберігаєте підписний секрет, який вони видають. Універсального флоу немає, тож дотримуйтеся документації конкретного продукту, з яким інтегруєтеся. Щодо dcast.tv зокрема, покладайтеся на офіційну Partner API та матеріали для розробників, а не припускайте, що екран вебхуків у споживчому дашборді існує.

Які типові події запускають вебхуки у відеоробочих процесах?

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

Як захистити й перевірити payload вебхуків?

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

Як обробляти дубльовані чи невдалі доставки вебхуків?

Зробіть свій обробник ідемпотентним, записуючи ID кожної обробленої події й пропускаючи повтори, оскільки провайдери повторюють спробу на будь-яку відповідь не-2xx чи таймаут. Швидко підтверджуйте статусом 2xx після безпечного постановлення події в чергу, обробляйте важку роботу асинхронно й тримайте dead-letter чергу плюс моніторинг, щоб невдалі доставки були видимими й відновлюваними.

Висновок

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

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

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