Tipos de Webhook

Atualizado: 07.04.2026

O Kinescope suporta webhooks de saída — notificações sobre eventos que ocorrem com seus vídeos ou streams. Quando ocorre um evento (por exemplo, um vídeo é processado ou um stream termina), o Kinescope envia uma solicitação HTTP para a URL que você especificou.

Para quem é este artigo

Desenvolvedores — precisam automatizar processos em seu sistema quando ocorrem eventos do Kinescope
Administradores de plataforma — precisam receber notificações sobre o status de processamento de vídeos
Engenheiros DevOps — precisam integrar o Kinescope com sistemas de monitoramento

Quais problemas os webhooks resolvem

Os webhooks permitem automatizar processos em seu sistema:

Rastreamento do processamento de vídeos — saiba quando um vídeo está pronto para assistir ou ocorreu um erro
Monitoramento de streams — receba notificações sobre conexões de streamers, fins de streams e outros eventos
Integração com seu sistema — atualize automaticamente os status em seu banco de dados ou envie notificações para os usuários

Como funciona

Você configura uma URL para receber webhooks (via API ou interface do Kinescope)
Quando ocorre um evento, o Kinescope envia uma solicitação HTTP POST para sua URL com dados JSON
Seu servidor manipula a solicitação e executa as ações necessárias (atualizações de status, envio de notificações, etc.)

Webhooks de vídeo

`media.update.status`

Enviado quando o status do vídeo é atualizado. Usado para rastrear processamento de vídeo, erros ou conclusão de publicação.

Exemplo 1: Atualização de status bem-sucedida

{
  "event": "media.update.status",
  "data": {
    "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
    "status": "done"
  }
}

Exemplo 2: Erro de processamento

{
  "event": "media.update.status",
  "data": {
    "id": "12706830-0e96-40d0-9a03-2e987c096466",
    "status": "error",
    "message": "import error: code=610100, message=cannot download link: https://example.ru/test.mp4, http_code=404"
  }
}

Status possíveis:

pending — vídeo aguardando processamento
uploading — vídeo sendo enviado
pre-processing — pré-processamento do vídeo
processing — vídeo sendo processado
aborted — processamento foi interrompido
done — vídeo pronto para assistir
error — ocorreu um erro durante o processamento
suspended — processamento/upload pausado

Webhooks de stream

`live.created`

Notificação sobre a criação de um novo evento de stream (via API ou interface).

{
  "event": "live.created",
  "data": {
    "event_id": "abc123-def456-ghi789"
  }
}

`live.connected`

Streamer conectado — stream RTMP começou a chegar ao servidor.

{
  "event": "live.connected",
  "data": {
    "event_id": "abc123-def456-ghi789"
  }
}

`live.disconnected`

Streamer desconectado — stream RTMP parou.

{
  "event": "live.disconnected",
  "data": {
    "event_id": "abc123-def456-ghi789"
  }
}

`live.finished`

Stream encerrado. A resposta também inclui video_id — o ID do vídeo de gravação do stream (se a gravação estava habilitada).

{
  "event": "live.finished",
  "data": {
    "event_id": "abc123-def456-ghi789",
    "video_id": "7127f2d7-0e96-40d0-9a03-2e987c096466"
  }
}

`live.cancelled`

Stream foi cancelado.

{
  "event": "live.cancelled",
  "data": {
    "event_id": "abc123-def456-ghi789"
  }
}

`live.enabled`

Stream está disponível para visualização pelos clientes.

{
  "event": "live.enabled",
  "data": {
    "event_id": "abc123-def456-ghi789"
  }
}

Exemplos de manipulação de webhooks

Exemplo 1: Atualizando o status do vídeo no banco de dados

Aqui está como manipular o webhook media.update.status e atualizar o status em seu banco de dados:

package main

import (
    "encoding/json"
    "log"
)

type MediaStatusEvent struct {
    Event string `json:"event"`
    Data  struct {
        ID      string `json:"id"`
        Status  string `json:"status"`
        Message string `json:"message,omitempty"`
    } `json:"data"`
}

func handleMediaStatusUpdate(event MediaStatusEvent) error {
    videoID := event.Data.ID
    status := event.Data.Status
    
    // Atualizar status no banco de dados
    // db.Exec("UPDATE videos SET status = ?, error_message = ?, updated_at = ? WHERE kinescope_id = ?",
    //     status, event.Data.Message, time.Now(), videoID)
    
    if status == "done" {
        notifyUser(videoID, "Seu vídeo está pronto para assistir!")
    }
    
    if status == "error" {
        log.Printf("Erro de processamento do vídeo %s: %s", videoID, event.Data.Message)
    }
    
    if status == "aborted" {
        notifyUser(videoID, "O processamento do vídeo foi interrompido")
    }
    
    return nil
}

Exemplo 2: Manipulando o fim do stream

Quando um stream termina, você pode processar automaticamente a gravação:

package main

type LiveFinishedEvent struct {
    Event string `json:"event"`
    Data  struct {
        EventID string `json:"event_id"`
        VideoID string `json:"video_id,omitempty"`
    } `json:"data"`
}

func handleLiveFinished(event LiveFinishedEvent) error {
    eventID := event.Data.EventID
    videoID := event.Data.VideoID
    
    // Atualizar status do stream
    // db.Exec("UPDATE live_events SET status = ?, recording_video_id = ?, finished_at = ? WHERE kinescope_event_id = ?",
    //     "finished", videoID, time.Now(), eventID)
    
    if videoID != "" {
        notifyViewers(eventID, "A gravação do stream está disponível: "+videoID)
    }
    
    return nil
}

Exemplo 3: Manipulador universal de webhook

Aqui está um exemplo de um manipulador universal que pode processar diferentes tipos de webhook:

package main

import (
    "encoding/json"
    "log"
    "net/http"
)

type WebhookEvent struct {
    Event string          `json:"event"`
    Data  json.RawMessage `json:"data"`
}

func handleWebhook(event WebhookEvent) error {
    switch event.Event {
    case "media.update.status":
        var e MediaStatusEvent
        json.Unmarshal(event.Data, &e.Data)
        e.Event = event.Event
        return handleMediaStatusUpdate(e)
        
    case "live.finished":
        var e LiveFinishedEvent
        json.Unmarshal(event.Data, &e.Data)
        e.Event = event.Event
        return handleLiveFinished(e)
        
    default:
        log.Printf("Tipo de evento desconhecido: %s", event.Event)
    }
    
    return nil
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    var event WebhookEvent
    if err := json.NewDecoder(r.Body).Decode(&event); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    
    if err := handleWebhook(event); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"success": true})
}

Configurando webhooks

Os webhooks são configurados via API do Kinescope. Especifique a URL do seu endpoint que receberá as notificações.

Importante: Seu endpoint deve retornar HTTP 200 em resposta ao tratamento bem-sucedido do webhook. Se o Kinescope receber um erro (4xx, 5xx), pode tentar novamente a solicitação.

Segurança

É recomendado verificar a autenticidade dos webhooks:

Verifique a origem da solicitação — certifique-se de que a solicitação vem do Kinescope
Use HTTPS — os webhooks devem ser enviados para URLs seguras
Valide os dados — verifique o formato e os campos obrigatórios na solicitação

Pronto! Agora você pode configurar webhooks e automatizar processos em seu sistema.

O que fazer a seguir?

Regras gerais da API — autorização e formato de solicitação
Kinescope API — documentação completa da API para configuração de webhooks
Upload de arquivos via API — upload automatizado de vídeos

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!