​
Webhook types

A webhook is a real-time callback that sends an HTTP POST request to your server-side app when a defined event happens in our Video Streaming service. This way, you instantly receive updates and can trigger automated actions without manual checks by constant pulling API. A single universal endpoint is used for all types of webhooks. 
{
  "type": "stream|video|restream",
  "message": { ... } 
}
Supported entities:
  1. Live streams – type: stream
  2. VOD videos – type: vod
  3. Restreamings – type: restream
The webhook will contain main fields of the entity for which the event occurred. This allows you to not pull the API to get additional data each time.

​
Webhooks for Live

When the state of a live stream changes, the system triggers a webhook with type stream. The payload contains a message.stream object with stream properties. Behaviour:
  • A webhook is fired on key state changes, such as a stream going live or stopping.
  • The payload allows you to track whether a stream is active, its source, and related metadata.
  • Both PUSH and PULL origins are supported.
Fields:
FieldTypeDescription
idintUnique identifier of the stream
livebooltrue if the stream is currently active, false if it has stopped
backup_livebooltrue if the backup source is currently active
recordingbooltrue if the stream is being recorded
client_user_idstringOptional client-defined user ID, null if not provided
client_entity_datastringOptional client metadata associated with the stream, null if not provided
pullbooltrue if the stream is pulled from an external origin, false if pushed
uristringThe source URI of the stream (e.g. HTTPS or SRT endpoint)
stream_source_typestringType of the stream source (e.g. https, rtmp, srt)
Example: Started stream: 
{
  "type": "stream",
  "message": {
    "stream": {
      "id": 1001,
      "live": true,
      "backup_live": false,
      "recording": false,
      "client_user_id": null,
      "client_entity_data": null,
      "pull": false,
      "uri": "srt://vp-push-ed1-srt.gvideo.co:5001?streamid=12345#aaabbbcccddd",
      "stream_source_type": "srt"
    }
  }
}
Stoped stream: 
{
  "type": "stream",
  "message": {
    "stream": {
      "id": 1002,
      "live": false,
      "backup_live": false,
      "recording": false,
      "client_user_id": null,
      "client_entity_data": null,
      "pull": true,
      "uri": "https://.../master.m3u8",
      "stream_source_type": "https"
    }
  }
}

​
Webhooks for VOD

A webhook with type video fires when a VOD file is created, processed, or becomes playable. Use the payload to track processing progress and available renditions. Behaviour:
  • Sent on key status changes of a video: empty → pending → viewable → ready or error. 
  • converted_videos[].status reflects per-rendition progress like processing or complete. 
Fields:
FieldTypeDescription
idintVideoID
slugstringPublic identifier used in playback URLs
namestringVideo name
durationintDuration of the video in milliseconds
stream_idint | nullStreamID if it was recorded from a Live stream, otherwise null
statusstringProcessing status of the video: empty, pending, viewable, ready, error
converted_videosarrayList of transcoded renditions with details
└─ namestringRendition label (e.g., vod1080p)
└─ statusstringRendition status
└─ mp4_urlstringDirect URL for a rendition in MP4 fromat
See the statuses of VOD processing in API docs: Example: Video uploaded: 
{
  "type": "video",
  "message": {
    "video": {
      "id": 2001,
      "slug": "bJkptcIp9a5wrowz",
      "name": "football_videoplayback_720",
      "duration": 43989,
      "stream_id": null,
      "status": "empty",
      "converted_videos": []
    }
  }
}
Video becomes viewable (not all renditions are ready yet, but video can be watched by end-users already): 
{
  "type": "video",
  "message": {
    "video": {
      "id": 2001,
      "slug": "bJkptcIp9a5wrowz",
      "name": "football_videoplayback_720",
      "duration": 43989,
      "stream_id": null,
      "status": "viewable",
      "converted_videos": [
        {
          "name": "4029_h264_720p",
          "status": "complete",
          "mp4_url": "https://102748.gvideo.io/videos/102748_bJkptcIp9a5wrowz/qid4029v1_h264_2700_720.mp4"
        },
        {
          "name": "4014_hevc_720p",
          "status": "processing",
          "mp4_url": "https://102748.gvideo.io/videos/102748_bJkptcIp9a5wrowz/qid4014v1_hevc_1620_720.mp4"
        },
        {
          "name": "3999_av1_720p",
          "status": "processing",
          "mp4_url": "https://102748.gvideo.io/videos/102748_bJkptcIp9a5wrowz/qid3999v1_av1_1350_720.mp4"
        }
      ]
    }
  }
}

​
Webhooks for Restream

When a restream changes state (for example, starts or stops), the system sends a webhook with type restream. The payload contains a message.restream object. Behaviour:
  • Fired whenever a restream goes live or stops.
  • Allows you to track the status of a specific restream linked to a live stream.
Fields:
FieldTypeDescription
idintUnique identifier of the restream.
namestringHuman-readable name of the restream.
stream_idintID of the source live stream that this restream is linked to.
livebooltrue if the restream is currently active, false if it stopped.
Example: Restream starts: 
{
  "type": "restream",
  "message": {
    "restream": {
      "id": 3001,
      "name": "RTMP from Brodcast#1 to Youtube",
      "stream_id": 1001,
      "live": true
    }
  }
}
Restream stops: 
{
  "type": "restream",
  "message": {
    "restream": {
      "id": 3001,
      "name": "RTMP from Brodcast#1 to Youtube",
      "stream_id": 1001,
      "live": false
    }
  }
}

​
Sending events

We deliver webhooks from IP addresses 92.223.112.0/24 and 92.223.123.0/24. So put them into the whitelist. Events are sent only once. If your server is unavailable, undelivered webhooks won’t be sent again.

​
How to enable webhooks

At the moment, webhooks can only be set up with our help. Tell us your end-point and we will install it in your account.
1. Prepare your HTTP server to receive webhooks. 2. Contact us via chat or email support@gcore.com and ask to enable the webhook integration. Specify your ID (personal client ID) and the URL of the server that will receive webhooks. You can find your ID in the Gcore Customer Portal.
your ID in the Gcore Customer Portal
The message template: “Good afternoon! Please configure the Video Streaming webhook integration for my account with ID… The URL of my server to send webhooks to is …”. 3. We will notify you when we configure the webhook integration. Testing: Also you can easily create and inspect webhook requests using web site https://webhook.site. For example, the temporary link look like https://webhook.site/56ce9331-4ec4-4fa1-bf23-4c4e14276f24 to capture and display incoming webhook payloads for debugging. Create your own and send it to us to set up.