Webhooks para automação de vídeo: como funcionam, payloads genéricos e exemplos em Node.js. Deixa claro que o painel público de criador do dcast.tv não oferece um fluxo genérico de configurações de webhooks — use a documentação real do fornecedor e os materiais da Partner API quando aplicável.
Junte-se a milhares de criadores que monetizam seu conteúdo com a DCAST.
Comece grátisWebhooks 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 ficar consultando uma API o tempo todo perguntando "o vídeo já ficou pronto?", o provedor envia uma mensagem no momento em que o evento ocorre. Em fluxos de vídeo, isso é a espinha dorsal da automação: conclusão de transcodificação, eventos do ciclo de vida da transmissão, disponibilidade da gravação e finalização do upload podem, todos, disparar o próximo passo do seu pipeline sem ninguém olhando um painel.
A mecânica é simples e consistente entre os provedores. O servidor que recebe valida a requisição (idealmente checando uma assinatura criptográfica), responde rápido com um status 2xx e enfileira qualquer trabalho pesado para processamento em segundo plano. Todo o resto — nomes de eventos, formatos de payload, comportamento de retentativa — varia por fornecedor, e é por isso que entender o padrão importa mais que decorar os campos de um único provedor.
A configuração é sempre específica do provedor. Você registra o seu endpoint HTTPS público no painel ou na API daquele fornecedor em particular — o serviço de encoding, a plataforma de ao vivo, o provedor de pagamentos e assim por diante. O fluxo típico é: cole a sua URL de callback, escolha quais tipos de evento quer receber e guarde com segurança qualquer segredo de assinatura que ele fornecer. Não existe uma "tela de webhooks" universal que abranja todos os fornecedores; você segue a documentação do produto específico com o qual está de fato integrando, porque a localização exata e a terminologia mudam a cada vez.
A experiência pública de criador no dcast.tv não inclui uma página de configurações genérica de "Webhooks" onde você adiciona URLs arbitrárias para eventos como "transcodificação concluída" ou "transmissão iniciada", apesar do que alguns rascunhos de SEO desatualizados afirmam. Não siga instruções que mandam o usuário fazer login em um painel do dcast.tv e clicar em uma "ação manual de webhook no painel" — não é assim que o produto de consumidor funciona, e copiar esses passos só vai gerar confusão.
Integrações de parceiro e de API — a documentação e as ferramentas voltadas a desenvolvedores ou às superfícies Pro/parceiro — são onde callbacks, eventos assinados e itens de roadmap relacionados pertencem, descritos na documentação oficial da Partner API e de desenvolvedor, e não em um fluxo fictício de painel de consumidor. A regra prática: trate qualquer texto de blog que prometa uma UI específica do dcast.tv como desatualizado, a menos que ele corresponda à documentação atual do produto. Na dúvida, confie na documentação oficial em vez de um tutorial, incluindo este.As strings exatas variam por provedor, mas as categorias de evento são notavelmente consistentes no setor:
Um pipeline bem projetado encadeia esses eventos: `upload concluído` dispara a transcodificação, `transcodificação concluída` aciona a geração de miniaturas e marca o ativo como publicável, e `gravação pronta` notifica os assinantes de que existe um replay. Cada evento faz uma tarefa e passa o bastão para o próximo.
Os payloads são quase sempre JSON. Sempre leia o schema real do seu provedor, porque os nomes de campo e o aninhamento diferem — o exemplo abaixo é genérico e apenas ilustrativo:
```json
{
"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 uma dor de cabeça real. Primeiro, nunca presuma que um campo existe — cheque-o de forma defensiva antes de usá-lo, porque 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 autoritativo na API do provedor, em vez de confiar cegamente no corpo do webhook, já que payloads podem ser falsificados ou reenviados.
```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');
});
```
O passo de segurança mais importante de todos é verificar que uma requisição veio genuinamente do seu provedor e não foi forjada. A maioria dos fornecedores assina cada requisição com um HMAC do corpo bruto usando o seu segredo compartilhado e envia o resultado em um cabeçalho. Seu trabalho é recalcular essa assinatura e compará-la em tempo constante:
```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)
);
}
```
Observe que a verificação de assinatura geralmente precisa do corpo bruto da requisição, exatamente como foi recebido. Se o seu parser de JSON já reserializou o corpo, os bytes podem diferir e a assinatura nunca vai bater — então capture o corpo bruto antes do parsing quando um provedor exigir isso.
Implemente idempotência guardando o ID de todo evento que você já processou e ignorando as duplicatas, porque os provedores vão entregar o mesmo evento mais de uma vez em soluços de rede. Retorne um status 2xx apenas depois de ter aceitado o evento com segurança — normalmente após gravá-lo em uma fila durável, não após concluir o trabalho de fato. Depois processe as tarefas demoradas de forma assíncrona, para que o remetente não sofra timeout. Se você fizer o trabalho pesado inline e demorar demais para responder, o provedor presume falha, faz a retentativa e você acaba processando o mesmo evento repetidamente.
1. Segurança: sempre use HTTPS, verifique as assinaturas em toda requisição e rejeite qualquer coisa que falhe na validação com um 401 ou 403.
2. Idempotência: presuma entregas duplicadas e deduplique por ID de evento, para que o reenvio nunca cobre em dobro, publique em dobro ou notifique em dobro.
3. Confirmação rápida: responda rápido com um 2xx e depois faça o trabalho de verdade em uma fila em segundo plano.
4. Monitoramento: registre toda entrega e falha, alerte em picos de respostas não-2xx e mantenha uma dead-letter queue para eventos que você não conseguiu processar.
Como um webhook precisa de uma URL publicamente acessível, testar no seu notebook exige um túnel. Ferramentas como o ngrok expõem 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 mostrando 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 lida com o payload corretamente antes de depender dele em produção.
Webhooks são callbacks HTTP que um provedor envia para uma URL que você controla quando um evento específico ocorre. Em fluxos de vídeo, eles notificam a sua aplicação em tempo real sobre coisas como conclusão de transcodificação, início e fim de transmissão, finalização de upload e disponibilidade de gravação — permitindo disparar o próximo passo automatizado sem polling.
O processo é sempre específico do provedor. Você registra o seu endpoint HTTPS público no painel ou na API daquele fornecedor, seleciona os tipos de evento que interessam e guarda o segredo de assinatura que ele fornecer. 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, apoie-se na Partner API oficial e nos materiais de desenvolvedor, em vez de presumir que existe uma tela de webhook no painel de consumidor.
Eventos comuns incluem "transcodificação concluída", "transmissão iniciada", "transmissão encerrada", "gravação pronta" e "upload concluído". As strings exatas variam por provedor, mas essas categorias cobrem a maioria das necessidades de automação.
Sirva o seu endpoint sobre HTTPS e verifique a assinatura criptográfica que o provedor envia com 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 autoritativo na API do provedor antes de tomar qualquer ação de consequência.
Torne o seu handler idempotente registrando todo ID de evento processado e ignorando as repetições, já que os provedores fazem retentativas em qualquer resposta não-2xx ou timeout. Confirme rápido com um 2xx após enfileirar o evento com segurança, processe o trabalho pesado de forma assíncrona e mantenha uma dead-letter queue mais monitoramento, para que entregas com falha fiquem visíveis e recuperáveis.
Webhooks são uma forma padrão e confiável de automatizar pipelines de vídeo — mas só quando a plataforma que você usa de fato os expõe, e só quando você os trata de forma segura e idempotente. Verifique o comportamento contra a documentação atual do produto, verifique as assinaturas em toda requisição e nunca dependa de passos de painel de exemplo que não existem em um dado produto. Construa o padrão corretamente uma vez, e a mesma disciplina se aplica a todo provedor que você venha a integrar.
Webhooks são callbacks HTTP que um provedor envia para uma URL que você controla quando um evento específico ocorre. Em fluxos de vídeo, eles notificam a sua aplicação em tempo real sobre coisas como conclusão de transcodificação, início e fim de transmissão, finalização de upload e disponibilidade de gravação — permitindo disparar o próximo passo automatizado sem polling.
O processo é sempre específico do provedor. Você registra o seu endpoint HTTPS público no painel ou na API daquele fornecedor, seleciona os tipos de evento que interessam e guarda o segredo de assinatura que ele fornecer. Não existe um fluxo universal, então siga a documentação do produto exato. No caso do dcast.tv, apoie-se na Partner API oficial e nos materiais de desenvolvedor, em vez de presumir que existe uma tela de webhook no painel de consumidor.
Eventos comuns incluem "transcodificação concluída", "transmissão iniciada", "transmissão encerrada", "gravação pronta" e "upload concluído". As strings exatas variam por provedor, mas essas categorias cobrem a maioria das necessidades de automação.
Sirva o seu endpoint sobre HTTPS e verifique a assinatura criptográfica que o provedor envia com 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 autoritativo na API do provedor antes de tomar qualquer ação de consequência.
Torne o seu handler idempotente registrando todo ID de evento processado e ignorando as repetições, já que os provedores fazem retentativas em qualquer resposta não-2xx ou timeout. Confirme rápido com um 2xx após enfileirar o evento com segurança, processe o trabalho pesado de forma assíncrona e mantenha uma dead-letter queue mais monitoramento, para que entregas com falha fiquem visíveis e recuperáveis.
Professional video streaming experts helping creators succeed.
