Skip to Content
WebhooksVisão geral

Webhooks

Os webhooks permitem receber notificações em tempo real sobre eventos no teu workspace Ignite. Em vez de fazeres polling à API à procura de alterações, os webhooks enviam dados para o teu servidor à medida que os eventos ocorrem.

O que são webhooks?

Os webhooks são callbacks HTTP disparados quando ocorrem eventos específicos. Quando um evento acontece (por exemplo, um vídeo é criado ou atualizado), o Ignite envia um pedido HTTP POST para o teu endpoint configurado com informação sobre o evento.

Casos de utilização

  • Sincronização com CMS — Manter o teu sistema de gestão de conteúdos externo alinhado com as alterações aos vídeos
  • Automatização de fluxos de trabalho — Disparar fluxos automáticos quando vídeos são criados, atualizados ou eliminados
  • Notificações — Enviar alertas à equipa quando o processamento do vídeo termina
  • Análise — Acompanhar eventos do ciclo de vida dos vídeos no teu próprio sistema de analytics

Como funciona

Criar uma subscrição de webhook

Configura uma subscrição de webhook na interface de administração do Ignite. Precisas de indicar:

  • Um URL de endpoint no teu servidor que aceite pedidos HTTP POST
  • Os tipos de evento a que queres subscrever-te

Receber eventos

Quando ocorre um evento subscrito, o Ignite envia um pedido HTTP POST para o teu endpoint com:

  • O tipo de evento no cabeçalho X-Webhook-Event
  • Uma assinatura para verificação no cabeçalho X-Webhook-Signature
  • Um ID de entrega único no cabeçalho X-Webhook-Delivery-Id
  • O objeto de vídeo completo como corpo JSON

Processar e responder

O teu endpoint deve:

  1. Verificar a assinatura do webhook
  2. Processar os dados do evento
  3. Devolver um código de estado 2xx no prazo de 30 segundos

Os webhooks podem chegar fora de ordem ou ser entregues mais do que uma vez. O teu cliente é responsável por verificar o timestamp updatedAt e o id do vídeo para garantir ordenação e consistência dos dados. Compara sempre o timestamp recebido com os dados guardados antes de aplicar atualizações e usa o cabeçalho X-Webhook-Delivery-Id para detetar e ignorar entregas duplicadas.

Subscrição de webhook

Uma subscrição de webhook é uma configuração que define para onde os eventos são enviados e que eventos escutar.

Propriedades da subscrição

PropriedadeTipoDescrição
idstringIdentificador único da subscrição
urlstringURL do endpoint para onde os eventos serão enviados (HTTP ou HTTPS)
eventsobjectQue tipos de evento estão ativos
events.videoCreatedbooleanReceber eventos quando vídeos são criados
events.videoUpdatedbooleanReceber eventos quando vídeos são atualizados
events.videoDeletedbooleanReceber eventos quando vídeos são eliminados
activebooleanSe o webhook está atualmente ativo
signingSecretstringChave secreta usada na verificação da assinatura (gerada automaticamente)
workspacestringO workspace a que este webhook pertence

Exemplo de objeto de subscrição

{
  "id": "507f1f77bcf86cd799439011",
  "url": "https://your-server.com/webhook",
  "events": {
    "videoCreated": true,
    "videoUpdated": true,
    "videoDeleted": false
  },
  "active": true,
  "signingSecret": "whsec_abc123...",
  "workspace": "507f1f77bcf86cd799439000"
}

Formato do pedido HTTP

Quando ocorre um evento, o Ignite envia um pedido POST para o teu endpoint:

Cabeçalhos

CabeçalhoDescrição
Content-Typeapplication/json
X-Webhook-EventO tipo de evento (por exemplo, video.created)
X-Webhook-SignatureAssinatura HMAC-SHA256 para verificação
X-Webhook-Delivery-IdIdentificador único desta entrega (útil para idempotência)

Corpo

O corpo do pedido contém o objeto de vídeo completo em JSON. Vê a documentação do objeto Video para a estrutura completa.

{
  "id": "507f1f77bcf86cd799439011",
  "title": "My Video",
  "status": "COMPLETE",
  "visibility": "public",
  "duration": 120,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  // ... all other video properties
}

Próximos passos

ConsultasTipos de eventos