Streaming de Vídeo

Webhooks em fluxos de vídeo: automatizando seu pipeline

Webhooks para automação de vídeo: como funcionam, payloads genéricos e exemplos em Node.js. Esclarece que o painel público de criadores do dcast.tv não oferece um fluxo genérico de configuração de webhooks; use a documentação real dos provedores e os materiais da Partner API quando for o caso.

dcast Team
9 min de leitura
Compartilhar:
Webhooks em fluxos de vídeo: automatizando seu pipeline no dcast.tv
On this page

Introdução aos webhooks

Os webhooks permitem que um sistema avise outro quando algo acontece, enviando uma requisição HTTP para uma URL que você controla. Em vez de a sua aplicação consultar uma API o tempo todo, perguntando "o vídeo já ficou pronto?", o provedor envia uma mensagem no instante em que o evento ocorre. Nos fluxos de vídeo, isso é a base da automação: a conclusão da transcodificação, os eventos do ciclo de vida de uma transmissão, a disponibilidade de uma gravação e a finalização de um upload podem disparar a próxima etapa do seu pipeline sem ninguém vigiando um painel.

Envie, transmita e venda seus vídeos. Comece no plano gratuito, sem cartão.

Comece grátis

A mecânica é simples e consistente entre os provedores. O servidor que recebe valida a requisição (de preferência conferindo uma assinatura criptográfica), responde rápido com um status 2xx e coloca na fila qualquer trabalho pesado para processamento em segundo plano. Todo o resto, como nomes de eventos, formato dos payloads e comportamento de novas tentativas, varia conforme o fornecedor, e é por isso que entender o padrão importa mais do que decorar os campos de um provedor específico.

Onde as URLs de webhook são configuradas

A configuração é sempre específica de cada provedor. Você registra o seu endpoint HTTPS público no painel ou na API daquele fornecedor em particular: o serviço de codificação, a plataforma de transmissão ao vivo, o provedor de pagamentos e assim por diante. O fluxo típico é: colar a sua URL de callback, escolher os tipos de evento que quer receber e guardar com segurança o segredo de assinatura que eles emitirem. Não existe uma "tela de webhooks" universal que sirva a todos os fornecedores; você segue a documentação do produto específico com o qual realmente está integrando, porque o local exato e a terminologia mudam a cada vez.

O DCAST e os produtos voltados a desenvolvedores

A experiência pública de criadores no dcast.tv não inclui uma página genérica de configurações de "Webhooks" na qual você adiciona URLs quaisquer para eventos como "transcodificação concluída" ou "transmissão iniciada".

As integrações de parceiros e de API, isto é, a documentação e as ferramentas voltadas a desenvolvedores ou às superfícies Pro/parceiros, são o lugar dos callbacks, dos eventos assinados e dos itens de roadmap relacionados, descritos na documentação oficial da Partner API e para desenvolvedores, e não em um fluxo fictício de painel para o consumidor. Na dúvida, confie na documentação oficial mais do que em um tutorial, inclusive este.

Eventos de webhook comuns em fluxos de vídeo

Os nomes exatos variam conforme o provedor, mas as categorias de eventos são notavelmente consistentes em todo o setor:

  • Transcodificação ou codificação concluída: o ativo está pronto para reprodução ou para a próxima etapa do pipeline (miniaturas, legendagem, publicação).
  • Transmissão iniciada / encerrada: o ciclo de vida da transmissão ao vivo, útil para análises, notificações e para disparar a gravação.
  • Gravação pronta: a versão de replay ou VOD de uma transmissão ao vivo já está disponível.
  • Upload concluído: a ingestão terminou e o arquivo bruto está armazenado com segurança.

Um pipeline bem projetado encadeia esses eventos: upload completed dá início à transcodificação, transcoding finished dispara a geração de miniaturas e marca o ativo como publicável, e recording ready avisa os inscritos de que existe um replay. Cada evento faz um trabalho e passa a bola para o próximo.

Entendendo os payloads de webhook

Os payloads são quase sempre JSON. Leia sempre o esquema real do seu provedor, porque os nomes dos campos e o aninhamento mudam; o exemplo abaixo é genérico e meramente ilustrativo:

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

Dois hábitos vão poupar você de dores de cabeça reais. Primeiro, nunca presuma que um campo existe: verifique antes de usá-lo, de forma defensiva, porque os provedores adicionam e renomeiam campos com o tempo. Segundo, trate o payload como uma notificação, não como a fonte da verdade. Para qualquer coisa importante, use o ID do payload para buscar o registro oficial na API do provedor, em vez de confiar cegamente no corpo do webhook, já que payloads podem ser falsificados ou reenviados.

Tratando webhooks com Node.js

Configurando um listener simples

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

Exemplo: ramificar pelo 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');
});

Verificando assinaturas

O passo de segurança mais importante é verificar se a requisição veio mesmo do seu provedor e não foi forjada. A maioria dos fornecedores assina cada requisição com um HMAC do corpo bruto da requisição, usando o segredo compartilhado, e envia o resultado em um cabeçalho. Cabe a você recalcular essa assinatura e compará-la em tempo 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)
  );
}

Observe que a verificação da assinatura geralmente exige o corpo bruto da requisição, exatamente como foi recebido. Se o seu parser de JSON já tiver reserializado o corpo, os bytes podem ser diferentes e a assinatura nunca vai bater; por isso, capture o corpo bruto antes de fazer o parse quando o provedor exigir.

Tratamento de erros e novas tentativas

Implemente a idempotência armazenando o ID de cada evento já processado e ignorando os duplicados, porque os provedores vão entregar o mesmo evento mais de uma vez durante instabilidades de rede. Retorne um status 2xx somente depois de aceitar o evento com segurança, normalmente depois de gravá-lo em uma fila durável, e não depois de concluir o trabalho em si. Em seguida, processe as tarefas demoradas de forma assíncrona, para que o remetente não estoure o tempo limite. Se você fizer o trabalho pesado na própria requisição e demorar demais para responder, o provedor presume uma falha, tenta de novo e você acaba processando o mesmo evento várias vezes.

Boas práticas

  1. Segurança: use sempre HTTPS, verifique as assinaturas em todas as requisições e rejeite com 401 ou 403 tudo o que falhar na validação.
  2. Idempotência: parta do princípio de que haverá entregas duplicadas e elimine duplicatas pelo ID do evento, para que um reenvio nunca cobre em dobro, publique em dobro nem notifique em dobro.
  3. Confirmação rápida: responda rápido com um 2xx e só então faça o trabalho de verdade em uma fila em segundo plano.
  4. Monitoramento: registre cada entrega e cada falha, crie alertas para picos de respostas não 2xx e mantenha uma dead-letter queue para os eventos que você não conseguiu processar.

Testando webhooks localmente

Como um webhook precisa de uma URL acessível publicamente, testar no seu notebook exige um túnel. Ferramentas como o ngrok expõem o seu servidor local em um endereço HTTPS público temporário, para que um provedor consiga alcançar http://localhost:3000 durante o desenvolvimento. Muitos provedores também oferecem um botão de "enviar evento de teste" e um log de entregas, que mostra cada tentativa e o código de resposta que você retornou. Use os dois para confirmar que o seu endpoint valida assinaturas, retorna 2xx rápido e trata o payload corretamente antes de depender dele em produção.

Conclusão

Os webhooks são uma forma padrão e confiável de automatizar pipelines de vídeo, mas só quando a plataforma que você usa realmente os oferece e só quando você os trata com segurança e idempotência. Confirme o comportamento na documentação atual do produto e verifique as assinaturas em todas as requisições. Construa o padrão corretamente uma vez, e a mesma disciplina vale para todos os provedores com que você vier a integrar.

Próximos passos e recursos

  • Use a documentação oficial do seu fornecedor de codificação ou de streaming para os tipos de evento, o formato do payload e os detalhes da verificação de assinatura.
  • Para o DCAST, baseie-se nos materiais publicados da Partner API / para desenvolvedores para entender o escopo da integração; evite presumir que exista uma interface de webhooks no painel do consumidor do dcast.tv.

Perguntas frequentes

O que são webhooks e como funcionam em fluxos de vídeo?

Webhooks são callbacks HTTP que um provedor envia para uma URL que você controla quando ocorre um evento específico. Nos fluxos de vídeo, eles avisam a sua aplicação em tempo real sobre coisas como a conclusão da transcodificação, o início e o fim de uma transmissão, a finalização de um upload e a disponibilidade de uma gravação, permitindo disparar a próxima etapa automatizada sem precisar consultar a API o tempo todo.

Como configuro webhooks em um provedor de vídeo?

O processo é sempre específico de cada provedor. Você registra o seu endpoint HTTPS público no painel ou na API daquele fornecedor, seleciona os tipos de evento que lhe interessam e guarda o segredo de assinatura que ele emitir. Não existe um fluxo universal, então siga a documentação do produto exato com o qual você está integrando. No caso específico do dcast.tv, baseie-se na Partner API oficial e nos materiais para desenvolvedores, em vez de presumir que exista uma tela de webhooks no painel do consumidor.

Quais são os eventos típicos que disparam webhooks em fluxos de vídeo?

Os eventos comuns incluem “transcodificação concluída”, “transmissão iniciada”, “transmissão encerrada”, “gravação pronta” e “upload concluído”. Os nomes exatos variam conforme o provedor, mas essas categorias cobrem a maior parte das necessidades de automação.

Como protejo e verifico os payloads de webhook?

Sirva o seu endpoint por HTTPS e verifique a assinatura criptográfica que o provedor envia a cada requisição, usando o seu segredo compartilhado e uma comparação em tempo constante. Trate o payload como uma notificação, e não como a fonte da verdade: use os IDs que ele contém para buscar o registro oficial na API do provedor antes de tomar qualquer ação de consequência.

Como lidar com entregas de webhook duplicadas ou com falha?

Torne o seu handler idempotente registrando o ID de cada evento processado e ignorando as repetições, já que os provedores tentam de novo diante de qualquer resposta não 2xx ou de um timeout. Confirme rápido com um 2xx depois de colocar o evento na fila com segurança, processe o trabalho pesado de forma assíncrona e mantenha uma dead-letter queue e um monitoramento, para que as entregas com falha fiquem visíveis e recuperáveis.

Documentação da API sobre este tema

streamingtransmissão ao vivovídeowebhooksfluxos de trabalhoautomação de vídeo
d

dcast Team

Especialistas em streaming de vídeo que ajudam os criadores a ter sucesso.

Comece hoje o seu negócio de vídeo

Envie, transmita e venda seus vídeos. Comece no plano gratuito, sem cartão.

Comece grátis