Mantenete en sync con webhooks firmados

Empujar, no hacer polling

En lugar de consultar la API para enterarte de cuándo arrancó un stream o terminó una grabación, dale a StreamHub una URL de callback. En cada evento del ciclo de vida hace POST de un sobre JSON firmado a tu backend — stream_started, stream_ended, vod_ready, recording_failed, y más.

Configurar el callback

Definí callbacks.url (e idealmente callbacks.secret) en la config de la app. De ahí en más, cada evento entrega un sobre:

{
  "id": "f2b1c8e4-...",
  "event": "vod_ready",
  "app": "live",
  "timestamp": "2026-06-30T12:00:00.000Z",
  "data": { /* payload específico del evento */ }
}

Lo acompañan headers de los que podés valerte: X-StreamHub-Event, X-StreamHub-Delivery (el id único), X-StreamHub-Timestamp, y — cuando hay un secreto configurado — X-StreamHub-Signature.

Verificar la firma

La firma es sha256= seguido del HMAC-SHA256 del cuerpo exacto recibido con tu secreto compartido. Compará siempre con una igualdad de tiempo constante:

const crypto = require('crypto');

function verificar(req, secreto) {
  const esperado = 'sha256=' + crypto
    .createHmac('sha256', secreto)
    .update(req.rawBody)        // los bytes exactos recibidos
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(esperado),
    Buffer.from(req.header('X-StreamHub-Signature')),
  );
}

Calculá el HMAC sobre los bytes crudos de la petición, no sobre un objeto re-serializado — la re-serialización puede cambiar los espacios y romper la coincidencia.

Manejar reintentos de forma idempotente

La entrega es al-menos-una-vez. StreamHub reintenta hasta 3 veces con backoff exponencial (500ms, 1s) y un timeout de 10s. Reintenta 5xx, 408 y 429; otros 4xx se tratan como rechazo y no se reintentan. Respondé 2xx para confirmar.

Como una entrega puede llegar más de una vez, deduplicá por X-StreamHub-Delivery (el UUID) y hacé tu handler idempotente. Guardá el id de entrega; si ya lo viste, confirmá y seguí.

Qué podés construir

Con callbacks firmados podés actualizar una insignia de "en vivo" en el instante en que un publicador conecta, disparar post-procesamiento cuando llega vod_ready, avisar a un ingeniero de guardia ante recording_failed, o escribir tu propia analítica — todo sin un solo bucle de polling. Y como los callbacks nunca lanzan de vuelta hacia el flujo de streaming, un endpoint inestable de tu lado nunca interrumpe el pipeline de medios.