Webhook Types

Updated: 28.04.2026

Kinescope supports outgoing webhooks — notifications about events that occur with your videos or streams. When an event occurs (e.g., a video is processed or a stream ends), Kinescope sends an HTTP request to the URL you specified.

Who this article is for

Developers — need to automate processes in their system when Kinescope events occur
Platform administrators — need to receive notifications about video processing status
DevOps engineers — need to integrate Kinescope with monitoring systems

What problems webhooks solve

Webhooks let you automate processes in your system:

Tracking video processing — know when a video is ready to watch or an error occurred
Stream monitoring — receive notifications about streamer connections, stream ends, and other events
Integration with your system — automatically update statuses in your database or send notifications to users

How it works

You configure a URL for receiving webhooks (via API or the Kinescope interface)
When an event occurs, Kinescope sends an HTTP POST request to your URL with JSON data
Your server handles the request and performs the needed actions (status updates, sending notifications, etc.)

Video webhooks

`media.update.status`

Sent when the video status is updated. Used to track video processing, errors, or publication completion.

Example 1: Successful status update

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

Example 2: Processing error

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

Possible statuses:

pending — video is waiting for processing
uploading — video is uploading
pre-processing — video pre-processing
processing — video is being processed
aborted — processing was aborted
done — video is ready to watch
error — an error occurred during processing
suspended — processing/uploading is paused

Stream webhooks

`live.created`

Notification about the creation of a new stream event (via API or interface).

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

`live.connected`

Streamer connected — RTMP stream started arriving at the server.

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

`live.disconnected`

Streamer disconnected — RTMP stream stopped.

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

`live.finished`

Stream ended. The response also includes video_id — the ID of the stream recording video (if recording was enabled).

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

`live.cancelled`

Stream was cancelled.

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

`live.enabled`

Stream is available for viewing by clients.

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

Webhook handling examples

Example 1: Updating video status in the database

Here is how to handle the media.update.status webhook and update the status in your database:

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
    
    // Update status in the database
    // 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, "Your video is ready to watch!")
    }
    
    if status == "error" {
        log.Printf("Video processing error %s: %s", videoID, event.Data.Message)
    }
    
    if status == "aborted" {
        notifyUser(videoID, "Video processing was aborted")
    }
    
    return nil
}

Example 2: Handling stream end

When a stream ends, you can automatically process the recording:

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
    
    // Update stream status
    // 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, "Stream recording is available: "+videoID)
    }
    
    return nil
}

Example 3: Universal webhook handler

Here is an example of a universal handler that can process different webhook types:

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("Unknown event type: %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})
}

Setting up webhooks

Webhooks are configured via the Kinescope API. Specify the URL of your endpoint that will receive notifications.

Important: Your endpoint must return HTTP 200 in response to successful webhook handling. If Kinescope receives an error (4xx, 5xx), it may retry the request.

Security

It is recommended to verify webhook authenticity:

Check the request source — make sure the request comes from Kinescope
Use HTTPS — webhooks should be sent to secure URLs
Validate data — check the format and required fields in the request

Done! You can now set up webhooks and automate processes in your system.

What’s next?

General API guidelines — authorization and request format
Kinescope API — full API documentation for webhook configuration
File upload via API — automated video upload

Still have questions? Write to the support chat within the Kinescope interface — our specialists will help!