# Tipos de Webhook 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** 1. **Você configura uma URL** para receber webhooks (via API ou interface do Kinescope) 2. **Quando ocorre um evento**, o Kinescope envia uma solicitação HTTP POST para sua URL com dados JSON 3. **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** ```json { "event": "media.update.status", "data": { "id": "7127f2d7-0e96-40d0-9a03-2e987c096466", "status": "done" } } ``` **Exemplo 2: Erro de processamento** ```json { "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). ```json { "event": "live.created", "data": { "event_id": "abc123-def456-ghi789" } } ``` ### **`live.connected`** Streamer conectado — stream RTMP começou a chegar ao servidor. ```json { "event": "live.connected", "data": { "event_id": "abc123-def456-ghi789" } } ``` ### **`live.disconnected`** Streamer desconectado — stream RTMP parou. ```json { "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). ```json { "event": "live.finished", "data": { "event_id": "abc123-def456-ghi789", "video_id": "7127f2d7-0e96-40d0-9a03-2e987c096466" } } ``` ### **`live.cancelled`** Stream foi cancelado. ```json { "event": "live.cancelled", "data": { "event_id": "abc123-def456-ghi789" } } ``` ### **`live.enabled`** Stream está disponível para visualização pelos clientes. ```json { "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: ```go 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: ```go 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: ```go 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? 1. **[Regras gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/)** — autorização e formato de solicitação 2. **[Referência da API](https://docs-br.kinescope.com/api/)** — documentação completa da API para configuração de webhooks 3. **[Upload de arquivos via API](https://docs-br.kinescope.com/developer-guides/file-upload-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!