Streaming de video

Webhooks en los flujos de trabajo de video: cómo automatizar tu pipeline

Webhooks para la automatización de video: cómo funcionan, payloads genéricos y ejemplos en Node.js. Aclara que el panel público de creadores de dcast.tv no ofrece un flujo genérico de configuración de webhooks: usa la documentación real de cada proveedor y los materiales de la API para partners cuando corresponda.

dcast Team
10 min de lectura
Compartir:
Webhooks en los flujos de trabajo de video: cómo automatizar tu pipeline en dcast.tv
On this page

Introducción a los webhooks

Los webhooks permiten que un sistema avise a otro cuando ocurre algo, enviando una solicitud HTTP a una URL que tú controlas. En lugar de que tu aplicación consulte una API sin parar preguntando “¿ya terminó el video?”, el proveedor te envía un mensaje en el instante en que ocurre el evento. En los flujos de trabajo de video, esta es la base de la automatización: la finalización de la transcodificación, los eventos del ciclo de vida de una transmisión, la disponibilidad de una grabación y la finalización de una carga pueden disparar el siguiente paso de tu pipeline sin que nadie esté mirando un panel.

Sube, transmite y vende tus videos. Empieza con el plan gratuito, sin tarjeta.

Comienza gratis

La mecánica es sencilla y consistente entre proveedores. El servidor receptor valida la solicitud (idealmente comprobando una firma criptográfica), responde rápido con un estado 2xx y deja en cola cualquier trabajo pesado para procesarlo en segundo plano. Todo lo demás —los nombres de los eventos, la forma de los payloads, el comportamiento de los reintentos— varía según el proveedor, y por eso es más importante entender el patrón que memorizar los campos de un solo proveedor.

Dónde se configuran las URL de los webhooks

La configuración es siempre específica de cada proveedor. Registras tu endpoint HTTPS público en el panel o en la API de ese proveedor en particular: el servicio de codificación, la plataforma de transmisión en vivo, el procesador de pagos, etc. El flujo habitual es este: pegas tu URL de callback, eliges qué tipos de eventos quieres recibir y guardas de forma segura el secreto de firma que te entreguen. No existe una “pantalla de webhooks” universal que abarque a todos los proveedores; hay que seguir la documentación del producto concreto con el que estás integrando, porque la ubicación exacta y la terminología cambian cada vez.

DCAST y los productos para desarrolladores

La experiencia pública para creadores en dcast.tv no incluye una página genérica de configuración de “Webhooks” donde puedas añadir URL arbitrarias para eventos como “transcodificación finalizada” o “transmisión iniciada”.

Las integraciones para partners y de API —la documentación y las herramientas dirigidas a desarrolladores o a las superficies Pro y de partners— son el lugar donde corresponden los callbacks, los eventos firmados y los elementos relacionados de la hoja de ruta, y se describen en la documentación oficial de la API para partners y para desarrolladores, no en un flujo ficticio de un panel para consumidores. Cuando tengas dudas, confía en la documentación oficial por encima de un tutorial, incluido este.

Eventos de webhook comunes en los flujos de trabajo de video

Las cadenas exactas varían según el proveedor, pero las categorías de eventos son notablemente consistentes en toda la industria:

  • Transcodificación o codificación finalizada: el recurso está listo para reproducirse o para el siguiente paso del pipeline (miniaturas, subtítulos, publicación).
  • Transmisión iniciada / finalizada: el ciclo de vida de la transmisión en vivo, útil para la analítica, las notificaciones y para disparar la grabación.
  • Grabación lista: la versión de repetición o VOD de una transmisión en vivo ya está disponible.
  • Carga completada: la ingesta terminó y el archivo original está almacenado de forma segura.

Un pipeline bien diseñado encadena estos eventos: upload completed inicia la transcodificación, transcoding finished dispara la generación de miniaturas y marca el recurso como publicable, y recording ready avisa a los suscriptores de que existe una repetición. Cada evento cumple una sola tarea y se la pasa al siguiente.

Cómo entender los payloads de los webhooks

Los payloads son casi siempre JSON. Lee siempre el esquema real de tu proveedor, porque los nombres de los campos y el anidamiento cambian; el ejemplo de abajo es genérico y solo ilustrativo:

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

Dos hábitos te ahorrarán dolores de cabeza reales. Primero, nunca des por hecho que un campo existe: compruébalo de forma defensiva antes de usarlo, porque los proveedores añaden y renombran campos con el tiempo. Segundo, trata el payload como una notificación, no como la fuente de verdad. Para cualquier cosa importante, usa el ID del payload para obtener el registro autoritativo desde la API del proveedor en lugar de confiar a ciegas en el cuerpo del webhook, ya que los payloads pueden suplantarse o reenviarse.

Cómo manejar webhooks con Node.js

Configurar un listener sencillo

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: bifurcar según el tipo de evento

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

Verificar las firmas

El paso de seguridad más importante es comprobar que una solicitud viene realmente de tu proveedor y no fue falsificada. La mayoría de los proveedores firman cada solicitud con un HMAC del cuerpo sin procesar de la solicitud, usando tu secreto compartido, y envían el resultado en un encabezado. Tu trabajo es volver a calcular esa firma y compararla en tiempo constante:

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

Ten en cuenta que la verificación de la firma suele necesitar el cuerpo sin procesar de la solicitud, exactamente como se recibió. Si tu analizador de JSON ya volvió a serializar el cuerpo, los bytes pueden diferir y la firma nunca coincidirá; por eso, captura el cuerpo sin procesar antes de analizarlo cuando el proveedor lo exija.

Manejo de errores y reintentos

Implementa la idempotencia guardando el ID de cada evento que hayas procesado y omitiendo los duplicados, porque los proveedores entregarán el mismo evento más de una vez cuando haya fallos de red. Devuelve un estado 2xx solo después de haber aceptado el evento de forma segura, normalmente tras escribirlo en una cola duradera, y no después de terminar el trabajo en sí. Luego procesa las tareas largas de forma asíncrona para que el remitente no agote el tiempo de espera. Si haces el trabajo pesado en línea y tardas demasiado en responder, el proveedor da por hecho que falló, reintenta y terminas procesando el mismo evento una y otra vez.

Mejores prácticas

  1. Seguridad: usa siempre HTTPS, verifica las firmas en cada solicitud y rechaza con un 401 o un 403 todo lo que no pase la validación.
  2. Idempotencia: da por hecho que habrá entregas duplicadas y deduplica por ID de evento para que un reenvío nunca cobre dos veces, publique dos veces ni notifique dos veces.
  3. Confirmación rápida: responde rápido con un 2xx y luego haz el trabajo real en una cola en segundo plano.
  4. Monitoreo: registra cada entrega y cada fallo, configura alertas ante picos de respuestas que no sean 2xx y mantén una cola de mensajes fallidos (dead-letter queue) para los eventos que no pudiste procesar.

Cómo probar webhooks de forma local

Como un webhook necesita una URL accesible públicamente, probar en tu laptop requiere un túnel. Herramientas como ngrok exponen tu servidor local en una dirección HTTPS pública temporal para que un proveedor pueda llegar a http://localhost:3000 durante el desarrollo. Muchos proveedores también ofrecen un botón de “enviar evento de prueba” y un registro de entregas que muestra cada intento y el código de respuesta que devolviste; usa ambos para confirmar que tu endpoint valida las firmas, devuelve 2xx con rapidez y maneja bien el payload antes de depender de él en producción.

Conclusión

Los webhooks son una forma estándar y confiable de automatizar pipelines de video, pero solo cuando la plataforma que usas realmente los ofrece y solo cuando los manejas de forma segura e idempotente. Verifica el comportamiento con la documentación vigente del producto y verifica las firmas en cada solicitud. Si construyes bien el patrón una vez, la misma disciplina te sirve con cada proveedor que integres en el futuro.

Próximos pasos y recursos

  • Usa la documentación oficial de tu proveedor de codificación o de streaming para conocer los tipos de eventos, el formato del payload y los detalles de la verificación de firmas.
  • Para DCAST, apóyate en los materiales publicados de la API para partners y para desarrolladores para entender el alcance de la integración; evita suponer que existe una interfaz de webhooks en un panel para consumidores en dcast.tv.

Preguntas frecuentes

¿Qué son los webhooks y cómo funcionan en los flujos de trabajo de video?

Los webhooks son callbacks HTTP que un proveedor envía a una URL que tú controlas cuando ocurre un evento específico. En los flujos de trabajo de video, avisan a tu aplicación en tiempo real de cosas como la finalización de la transcodificación, el inicio y el fin de una transmisión, la finalización de una carga y la disponibilidad de una grabación, y te permiten disparar el siguiente paso automatizado sin tener que consultar de forma constante.

¿Cómo configuro webhooks con un proveedor de video?

El proceso es siempre específico de cada proveedor. Registras tu endpoint HTTPS público en el panel o en la API de ese proveedor, seleccionas los tipos de eventos que te interesan y guardas el secreto de firma que te entreguen. No hay un flujo universal, así que sigue la documentación del producto exacto con el que estás integrando. En el caso específico de dcast.tv, apóyate en la API oficial para partners y en los materiales para desarrolladores, en lugar de suponer que existe una pantalla de webhooks en un panel para consumidores.

¿Cuáles son los eventos típicos que disparan webhooks en los flujos de trabajo de video?

Los eventos comunes incluyen “transcodificación finalizada”, “transmisión iniciada”, “transmisión finalizada”, “grabación lista” y “carga completada”. Las cadenas exactas varían según el proveedor, pero estas categorías cubren la mayoría de las necesidades de automatización.

¿Cómo protejo y verifico los payloads de los webhooks?

Sirve tu endpoint por HTTPS y verifica la firma criptográfica que el proveedor envía con cada solicitud, usando tu secreto compartido y una comparación en tiempo constante. Trata el payload como una notificación y no como la fuente de verdad: usa los ID que contiene para obtener el registro autoritativo desde la API del proveedor antes de realizar cualquier acción importante.

¿Cómo manejo las entregas duplicadas o fallidas de webhooks?

Haz que tu manejador sea idempotente registrando el ID de cada evento procesado y omitiendo los repetidos, ya que los proveedores reintentan ante cualquier respuesta que no sea 2xx o ante un tiempo de espera agotado. Confirma rápido con un 2xx después de poner el evento en cola de forma segura, procesa el trabajo pesado de forma asíncrona y mantén una cola de mensajes fallidos junto con monitoreo para que las entregas fallidas sean visibles y recuperables.

Documentación de la API sobre este tema

streamingtransmisión en vivovideowebhooksflujos de trabajoautomatización de video
d

dcast Team

Expertos en transmisión de video que ayudan a los creadores a tener éxito.

Comienza hoy tu negocio de video

Sube, transmite y vende tus videos. Empieza con el plan gratuito, sin tarjeta.

Comienza gratis