Webhooks na seção “Avatares de vídeo”: notificação ao seu servidor quando o vídeo estiver pronto

Webhooks na seção "Avatares de vídeo" é uma forma de saber se o vídeo está pronto, sem atualizar manualmente a página: assim que o vídeo for concluído, uma solicitação POST é enviada para o endereço do seu servidor, e o próprio servidor decide o que fazer a seguir - escrever o link para o banco de dados, enviar o arquivo para o cliente ou iniciar a próxima etapa. A aba é necessária para quem faz vídeos em lote ou integra a geração de avatares em seu produto: em vez de verificações intermináveis ​​​​de “pronto ou ainda não”, uma breve notificação chega exatamente no momento certo.

Por que isso é necessário?

Renderizar um vídeo não é uma operação instantânea e não adianta esperar por isso em uma aba aberta. De acordo com medições da plataforma datadas de 07/09/2026, um vídeo Kling 3.0 de cinco segundos em 1080p é considerado uma média de 115 segundos, e em 95% dos casos cabe em 165. Para Sora 2, a mesma tarefa leva em média cerca de 145 segundos. Se você verificar o status a cada poucos segundos, dezenas de solicitações vazias aparecerão em um vídeo; O webhook aparece apenas uma vez – quando o resultado realmente aparece.

O volume também fala por si. De acordo com o registro de geração da plataforma, ao longo de 30 dias (3 de setembro a 2 de outubro de 2026), foram iniciadas 3.292 tarefas de vídeo, das quais 2.369 concluídas com sucesso. Os vídeos são contados em segundo plano e terminam em momentos diferentes – isso não pode ser rastreado manualmente e um gerenciador de notificações simples resolve o problema sozinho.

O que a guia “Webhooks” faz?

É tudo uma questão de entregar notificações, sem mágica. Você cadastra um endereço, escolhe quais eventos deseja assinar e recebe um segredo de assinatura. A lista de endpoints registrados é armazenada ali: você pode ver o endereço, eventos selecionados, status e se o endpoint tem um segredo. O segredo pode ser relançado (o antigo irá parar de funcionar imediatamente) ou o endpoint pode ser totalmente excluído.

O evento vem apenas dos seus vídeos: o vídeo de outra pessoa não vai sair, mesmo que tenha sido contabilizado no mesmo momento. Há também um registro de eventos entregues – é conveniente verificar se algo realmente chegou ao seu servidor.

Como começar - passo a passo

1. Seção aberta "Avatares de vídeo" e painel webhook no endereço direto /ru/avatars?tab=webhooks.
2. Faça login na sua conta: a configuração não está disponível para convidados; quando clicado, uma janela de login será aberta.
3. No campo “Endpoint Address”, insira o endereço HTTPS público do seu servidor, por exemplo https://example.com/avatar-webhook. HTTP não funcionará - a entrega e a assinatura são projetadas para um canal seguro.
4. Marque os eventos necessários. Se você não selecionar nada, você estará inscrito em todos os eventos de uma só vez.
5. Clique em "Adicionar ponto de extremidade". Imediatamente após a criação, o segredo da assinatura aparecerá - copie e salve-o: ele não será exibido novamente.
6. Caso você ainda não possua servidor próprio, clique em “Substituir nosso receptor” - então as notificações serão acumuladas no log de eventos entregues diretamente na aba.

Como ter certeza de que a solicitação é nossa e não falsa

Cada solicitação é acompanhada por um cabeçalho de assinatura - este é o HMAC-SHA256, calculado a partir do corpo bruto da solicitação como seu segredo. Do seu lado, conte a mesma assinatura e compare: se não corresponder, descartamos a solicitação. Nosso receptor faz exatamente isso e responde com 401 a uma assinatura incorreta. Mantenha o segredo no servidor, nas variáveis ​​de ambiente, e não no código do cliente.

O que vem na solicitação

O corpo é JSON simples com o tipo de evento e os dados da entidade. Por exemplo, para um vídeo finalizado, este é o evento BLK0 com o identificador de vídeo dentro. A lista completa dos tipos de eventos disponíveis é mostrada na aba: você pode classificá-los e deixar apenas o que seu serviço realmente precisa.

Quanto custa isso

Registro de endpoint, reliberação secreta, exclusão e log de eventos não cancelam tokens - isso é configuração de notificação, não geração. Os tokens são gastos apenas no vídeo em si: o preço em tokens fica visível antes do lançamento e, caso a tarefa falhe, o que foi baixado é devolvido. Não há assinatura: novos usuários recebem tokens iniciais para seus primeiros testes.

Com o que combinar

• "Tarefas em lote" — lançar dezenas de vídeos com uma tarefa; Um webhook eliminará a necessidade de controle manual de prontidão.
• "Biblioteca de mídia" — armazenamento de códigos-fonte e arquivos finalizados.
• "Tradução de vídeo" E "Corte de clipe" — próximos passos após geração.

Perguntas frequentes

Qual endereço é adequado para um webhook?

Somente HTTPS público. Endereços locais e HTTP não são aceitos: a notificação deve passar por um canal seguro e seu servidor deve ser acessível externamente.

É possível receber notificações se não houver servidor?

Sim. Clique em “Substituir nosso receptor” - os eventos serão acumulados no log “Eventos Entregues” da aba, podendo ser visualizados sem o seu backend.

O que fazer se a assinatura não corresponder?

Verifique se você está lendo HMAC-SHA256 do corpo da solicitação bruta (e não do JSON analisado) e se está usando o segredo atual: após a reemissão, o antigo para de funcionar imediatamente.

Isso é pago?

A configuração de webhooks não cancela tokens. Os tokens são gastos apenas na geração de vídeos – seu preço é visível antes do lançamento; Não há assinatura, novos usuários recebem tokens iniciais.