FlowData

Como configuro webhooks para o processamento de mídia?

Publicado em 10. novembro 2026

As tarefas de mídia rodam em segundo plano e podem levar de segundos a uma hora, dependendo do arquivo. Para que o seu software não precise ficar perguntando, o FlowData envia um retorno ao seu servidor assim que uma tarefa termina ou falha. Para isso, você configura um endpoint de webhook.

Criando um endpoint

  1. À esquerda, em Processamento de mídia, abra Webhooks.
  2. Clique em Criar endpoint.
  3. Informe a URL do seu servidor. Ela deve começar com https:// e ser acessível publicamente.
  4. Opcional: informe em Descrição (opcional) para que serve o endpoint.
  5. Escolha os Eventos: job.finished para tarefas concluídas e job.failed para tarefas com falha.
  6. Se precisar, marque Endpoint padrão. Mais detalhes abaixo.
  7. Clique em Salvar.

Logo em seguida, o FlowData mostra o Segredo de assinatura. Ele começa com whsec_. Copie-o imediatamente e guarde-o no seu servidor, pois ele é exibido somente esta vez. Confirme com Salvei o segredo.

A lista de endpoints

Para cada endpoint você vê a URL com descrição e ID, os Eventos assinados, o Status (Ativo ou Inativo, além da marcação Padrão) e o resultado do Último teste.

Os endpoints de webhook com eventos, status e o resultado do último teste

À direita de cada linha ficam as ações:

  • Enviar entrega de teste: envia um retorno de teste com o evento webhook.test ao seu servidor, para verificar se ele está acessível e respondendo.
  • Editar: altere URL, descrição, eventos e a opção de padrão. Aqui você também pode pausar um endpoint em Ativo. Endpoints inativos não recebem retornos e não podem ser usados em novas tarefas.
  • Renovar segredo: cria um novo segredo de assinatura. O anterior continua assinando por 24 horas, para que você mude o seu servidor sem interrupção.
  • Excluir: remove o endpoint. Entregas pendentes para ele são abandonadas.

Os endpoints também podem ser listados, criados e excluídos pela API em https://api.flowdata.one/v1/media/webhook-endpoints.

Usando um endpoint em uma tarefa

Na tarefa, informe o ID do endpoint, que aparece abaixo da URL na lista:

"callback": { "endpoint_id": "SEU_ID_DE_ENDPOINT" }

Como alternativa, você pode informar um endereço livre com "callback": { "url": "https://…" }. O FlowData assina esses retornos com o segredo do Endpoint padrão. Se não houver endpoint padrão, eles são enviados sem assinatura. Cada equipe tem no máximo um endpoint padrão.

Verificando os retornos

Cada retorno é assinado conforme o padrão aberto "Standard Webhooks" e contém os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. O corpo contém o evento, a tarefa com todas as saídas e os seus metadados. As bibliotecas comuns de Standard Webhooks verificam a assinatura sem código próprio. O procedimento exato, com exemplo, está na documentação da API de processamento de mídia.

O seu servidor deve:

  • verificar a assinatura com o corpo sem alterações e rejeitar carimbos de tempo com diferença de mais de cinco minutos
  • responder com um status 2xx em até dez segundos (redirecionamentos não são seguidos)
  • ignorar webhook-id já processados, pois o valor permanece o mesmo nas repetições

Se uma entrega falhar

Se o seu servidor não responder a tempo ou retornar um erro, o FlowData repete a entrega até sete vezes, em intervalos crescentes de 30 segundos a 6 horas. Na visão de detalhes de uma tarefa, em Entregas de webhook, você vê o status de cada retorno:

  • Pendente: a entrega ainda está a caminho
  • Entregue: o seu servidor a aceitou
  • Nova tentativa: a última tentativa falhou, e a Próxima tentativa aparece ao lado
  • Desistida: todas as tentativas falharam

Quando o seu servidor voltar a ficar acessível, clique no ícone de seta Enviar novamente para disparar a entrega na hora. Há mais sobre a visão de detalhes em Como acompanho o status das minhas tarefas de mídia?.

Este artigo foi útil?

Voltar para Processamento de mídia