Типы вебхуков

Обновлено: 28.12.2025

Kinescope поддерживает исходящие вебхуки — это уведомления о событиях, которые происходят с вашими видео или трансляциями. Когда происходит событие (например, видео обработалось или трансляция завершилась), Kinescope отправляет HTTP-запрос на указанный вами URL.

Кому подходит эта статья

Разработчикам — нужно автоматизировать процессы в системе при событиях Kinescope
Администраторам платформ — требуется получать уведомления о статусе обработки видео
DevOps-инженерам — нужно интегрировать Kinescope с системами мониторинга

Какие задачи решают вебхуки

Вебхуки позволяют автоматизировать процессы в вашей системе:

Отслеживание обработки видео — узнайте, когда видео готово к просмотру или произошла ошибка
Мониторинг трансляций — получайте уведомления о подключении стримера, завершении трансляции и других событиях
Интеграция с вашей системой — автоматически обновляйте статусы в вашей базе данных или отправляйте уведомления пользователям

Как это работает

Вы настраиваете URL для получения вебхуков (через API или интерфейс Kinescope)
При наступлении события Kinescope отправляет HTTP POST-запрос на ваш URL с JSON-данными
Ваш сервер обрабатывает запрос и выполняет нужные действия (обновление статуса, отправка уведомлений и т.д.)

Вебхуки для видео

`media.update.status`

Отправляется при обновлении статуса видео. Используется для отслеживания процессов обработки видео, ошибок или завершения публикации.

Пример 1: Успешное обновление статуса

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

Пример 2: Ошибка при обработке

{
  "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"
  }
}

Возможные статусы:

pending — видео ожидает обработки
uploading — видео загружается
pre-processing — предобработка видео
processing — видео обрабатывается
aborted — обработка прервана
done — видео готово к просмотру
error — произошла ошибка при обработке
suspended — обработка/загрузка приостановлена

Вебхуки для трансляций

`live.created`

Уведомление о создании нового события трансляции (через API или интерфейс).

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

`live.connected`

Стример подключился — RTMP поток начал поступать на сервер.

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

`live.disconnected`

Стример отключился — RTMP поток прекратился.

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

`live.finished`

Трансляция завершена. В ответе также приходит video_id — ID видео с записью трансляции (если запись была включена).

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

`live.cancelled`

Трансляция отменена.

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

`live.enabled`

Трансляция доступна для просмотра клиентами.

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

Примеры обработки вебхуков

Пример 1: Обновление статуса видео в базе данных

Вот как можно обработать вебхук media.update.status и обновить статус в вашей базе данных:

package main

import (
    "encoding/json"
    "log"
    "time"
)

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

// Пример обработки вебхука media.update.status
func handleMediaStatusUpdate(event MediaStatusEvent) error {
    videoID := event.Data.ID
    status := event.Data.Status
    
    // Обновляем статус в базе данных
    // 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, "Ваше видео готово к просмотру!")
    }
    
    // Если произошла ошибка, логируем её
    if status == "error" {
        log.Printf("Ошибка обработки видео %s: %s", videoID, event.Data.Message)
    }
    
    // Если обработка прервана, уведомляем пользователя
    if status == "aborted" {
        notifyUser(videoID, "Обработка видео была прервана")
    }
    
    return nil
}

Пример 2: Обработка завершения трансляции

Когда трансляция завершается, можно автоматически обработать запись:

package main

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

// Пример обработки вебхука live.finished
func handleLiveFinished(event LiveFinishedEvent) error {
    eventID := event.Data.EventID
    videoID := event.Data.VideoID
    
    // Обновляем статус трансляции
    // 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, "Запись трансляции доступна: "+videoID)
    }
    
    return nil
}

Пример 3: Универсальный обработчик вебхуков

Вот пример универсального обработчика, который может обрабатывать разные типы вебхуков:

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("Неизвестный тип события: %s", event.Event)
    }
    
    return nil
}

// HTTP обработчик
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})
}

Настройка вебхуков

Вебхуки настраиваются через API Kinescope. Укажите URL вашего эндпоинта, который будет принимать уведомления.

Важно: Ваш эндпоинт должен возвращать HTTP 200 в ответ на успешную обработку вебхука. Если Kinescope получит ошибку (4xx, 5xx), он может повторить запрос.

Безопасность

Рекомендуется проверять подлинность вебхуков:

Проверяйте источник запроса — убедитесь, что запрос приходит от Kinescope
Используйте HTTPS — вебхуки должны отправляться на защищённые URL
Валидируйте данные — проверяйте формат и обязательные поля в запросе

Всё! Теперь вы можете настроить вебхуки и автоматизировать процессы в вашей системе.

Что дальше?

После настройки вебхуков рекомендуем:

Общие правила API — авторизация и формат запросов
Kinescope API — полная документация API для настройки вебхуков
Загрузка файлов через API — автоматическая загрузка видео

Остались вопросы? Напишите в чат поддержки — специалисты помогут!