Webhooks en flujos de video: automatiza tu pipeline

Introducción a los webhooks

Los webhooks permiten que un sistema notifique a otro cuando ocurre algo, enviando una solicitud HTTP a una URL que tú controlas. En los flujos de video se usan a menudo para avisar de la finalización de la transcodificación, de eventos del ciclo de vida de una transmisión o de la disponibilidad de un recurso. El servidor receptor valida la solicitud (idealmente con una firma), responde rápido con un estado 2xx y encola cualquier tarea pesada.

La diferencia clave frente al polling (consultar la API cada pocos segundos para ver si algo cambió) es la eficiencia: en lugar de preguntar "¿ya terminó?" mil veces, el proveedor te avisa una sola vez, en el instante exacto. Para un pipeline de video —donde la transcodificación de un archivo largo puede tardar minutos u horas— esto elimina latencia y carga inútil sobre ambos sistemas.

Un flujo típico de extremo a extremo. Un usuario sube un video → tu backend lo envía al servicio de codificación → el servicio transcodifica en varias calidades → cuando termina, dispara un webhook `transcoding_finished` a tu endpoint → tu servidor marca el video como "listo", genera miniaturas, notifica al usuario y publica el contenido. Sin webhooks, tendrías que sondear el estado repetidamente y el usuario esperaría más de lo necesario.

Dónde se configuran las URL de webhook

La configuración siempre es específica de cada proveedor. Registras tu endpoint HTTPS público en el panel o la API de ese proveedor (servicio de codificación, plataforma en vivo, procesador de pagos, etc.): pegas la URL de callback, eliges los tipos de evento y guardas el secreto de firma que te entreguen. No existe un flujo universal; sigue la documentación del producto con el que realmente te integras.

Tu endpoint debe cumplir tres requisitos básicos: ser accesible públicamente por HTTPS (los proveedores rechazan HTTP plano y las URLs locales), responder rápido (por lo general en menos de unos segundos) y estar siempre disponible o preparado para reintentos. Durante el desarrollo, herramientas de túnel como las que exponen tu `localhost` a una URL pública temporal te permiten probar sin desplegar.

DCAST y los productos orientados a desarrolladores

La experiencia pública de creador en dcast.tv no incluye una página genérica de ajustes de "Webhooks" donde agregar URLs arbitrarias para eventos como "transcodificación finalizada" o "transmisión iniciada", como describían borradores de SEO desactualizados. No sigas instrucciones que le pidan al usuario iniciar sesión en un panel de dcast.tv y hacer clic en una "acción manual de webhook del panel": así no funciona el producto de consumo.

Las integraciones de socios y de API (incluida la documentación y las herramientas dirigidas a desarrolladores o a superficies Pro/de socios) pueden describir callbacks, eventos firmados o elementos de la hoja de ruta en la documentación oficial de la Partner API y para desarrolladores, no en un flujo ficticio de panel de consumo. Considera desactualizado cualquier texto de blog que prometa una interfaz específica de dcast.tv si no coincide con la documentación actual del producto.

La regla general que conviene interiorizar: la superficie de automatización vive en la capa de desarrollador/socio, no en el panel del creador final. Si construyes sobre DCAST, parte de la Partner API y confirma cada nombre de evento, cada campo de payload y cada mecanismo de firma contra la documentación vigente antes de escribir código que dependa de ellos.

Eventos de webhook comunes en flujos de video

Los nombres de evento típicos (las cadenas exactas varían según el proveedor) incluyen:

• Transcodificación o codificación finalizada — el recurso está listo para reproducirse o para el siguiente paso del pipeline
• Transmisión iniciada / finalizada — ciclo de vida en vivo para analítica o grabación
• Grabación lista — repetición o VOD disponible
• Carga completada — la ingesta terminó
• Error de procesamiento — la codificación o la ingesta falló y requiere reintento o alerta

Diseña tu manejador pensando en que aparecerán eventos nuevos con el tiempo: no asumas un conjunto cerrado. Un `switch` con una rama `default` que registre (sin fallar) los eventos desconocidos evita que una actualización del proveedor rompa tu servicio.

Entender los payloads de webhook

Los payloads suelen ser JSON. Consulta siempre el esquema de tu proveedor; a continuación solo se muestra un ejemplo genérico:

```json

{

"event": "transcoding_finished",

"video_id": "12345",

"status": "success",

"filename": "example_video.mp4",

"timestamp": "2023-10-05T12:00:00Z"

}

```

Fíjate en tres piezas que casi siempre necesitarás: un identificador de evento único (para idempotencia), un identificador del recurso (`video_id`, `stream_id`) para saber sobre qué actuar, y un timestamp para ordenar eventos que puedan llegar desordenados. Nunca confíes ciegamente en el cuerpo: valídalo contra el esquema esperado y trata los campos ausentes como un error controlado, no como una excepción que tumba el proceso.

Manejar webhooks con Node.js

Configurar un listener simple

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

});

```

Ejemplo: ramificar según el tipo de evento

```javascript

app.post('/webhook', (req, res) => {

const payload = req.body;

switch (payload.event) {

case 'transcoding_finished':

// marca el video como listo, genera miniaturas, notifica al usuario

console.log('Transcoding finished for video ' + payload.video_id);

break;

case 'stream_started':

console.log('Stream started: ' + payload.stream_id);

break;

default:

// no falles ante eventos nuevos o desconocidos

console.log('Unhandled event: ' + payload.event);

}

res.status(200).send('Webhook received');

});

```

Verificar la firma antes de confiar en el payload

La mayoría de los proveedores firman cada solicitud con HMAC usando un secreto compartido. Verifica la firma con el cuerpo crudo (raw body), no con el JSON ya parseado, porque cualquier reserialización cambia los bytes y rompe la comparación:

```javascript

const crypto = require('crypto');

app.post('/webhook',

express.raw({ type: 'application/json' }),

(req, res) => {

const signature = req.header('X-Signature');

const expected = crypto

.createHmac('sha256', process.env.WEBHOOK_SECRET)

.update(req.body) // req.body es un Buffer crudo aquí

.digest('hex');

// comparación en tiempo constante para evitar timing attacks

const ok = signature && crypto.timingSafeEqual(

Buffer.from(signature),

Buffer.from(expected)

);

if (!ok) return res.status(401).send('Invalid signature');

const payload = JSON.parse(req.body.toString());

// ...procesa el evento

res.status(200).send('OK');

}

);

```

Manejo de errores, idempotencia y reintentos

Los proveedores reintentan cuando no reciben un 2xx, así que el mismo evento puede llegar más de una vez. Implementa idempotencia almacenando los IDs de evento ya procesados (en Redis o en tu base de datos) y descartando los duplicados:

```javascript

async function handleEvent(payload) {

const already = await store.exists('evt:' + payload.event_id);

if (already) return; // duplicado: ignorar

await store.set('evt:' + payload.event_id, '1', 'EX', 86400);

// ...ejecuta la lógica real una sola vez

}

```

Devuelve un 2xx solo después de haber aceptado el evento de forma segura (por ejemplo, tras encolarlo), no después de terminar todo el trabajo pesado. Procesa las tareas largas de manera asíncrona en una cola para que el emisor no agote su tiempo de espera y no te reenvíe el evento por creer que fallaste.

Buenas prácticas

1. Seguridad: HTTPS obligatorio, verifica las firmas con el raw body y rechaza las solicitudes inválidas con 401.

2. Idempotencia: guarda los IDs de evento y maneja las entregas duplicadas sin efectos secundarios repetidos.

3. ACK rápido: responde con 2xx pronto y ejecuta el trabajo pesado en una cola en segundo plano.

4. Tolerancia a eventos nuevos: una rama `default` que registre lo desconocido en vez de fallar.

5. Monitoreo: registra cada entrega, su latencia y sus fallos; alerta si el volumen cae a cero (señal de que el endpoint o la configuración se rompió).

6. Orden y timestamps: no asumas que los eventos llegan en orden; usa el timestamp del payload para reconstruir la secuencia.

Diagnóstico de problemas comunes

• No llegan webhooks: confirma que la URL sea pública y HTTPS, revisa que el evento esté suscrito en el proveedor y busca en el panel del proveedor los intentos fallidos y sus códigos de respuesta.
• Firmas que no coinciden: casi siempre es porque se verificó contra el body parseado en lugar del crudo, o porque un middleware modificó el cuerpo antes de la verificación.
• Eventos duplicados: son normales; el problema real es no tener idempotencia. Añade el registro de IDs de evento.
• Timeouts: tu manejador tarda demasiado. Mueve el trabajo a una cola y responde de inmediato.

Conclusión

Los webhooks son una forma estándar de automatizar pipelines de video cuando tu plataforma real los expone. Verifica el comportamiento contra la documentación actual del producto; no confíes en pasos de panel de ejemplo que no existen en un producto concreto. Diseña para la realidad de la producción: firmas verificadas, idempotencia, ACK rápido y tolerancia a eventos nuevos y duplicados.

Próximos pasos y recursos

• Usa la documentación oficial de tu proveedor de codificación o streaming para conocer los tipos de evento, el formato del payload y la verificación de firmas.
• Para DCAST, apóyate en los materiales publicados de la Partner API / para desarrolladores a fin de conocer el alcance de la integración; evita suponer una interfaz de webhooks de panel de consumo en dcast.tv.
• Prueba tu endpoint localmente con un túnel HTTPS y payloads de ejemplo antes de conectarlo a producción.