Webhooks on system state changes

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|video_delete|restream",
  "message": { ... } 
}

Supported entities:

1. Live streams – type: stream
2. VOD videos:
   • on state change – type: video
   • on delete – type: video_delete
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.

Behavior:

• A webhook is fired on key state changes, such as ingest start, transcoding start, or stream stop.
• The payload allows you to track whether a stream is active, whether playback output is ready, its source, and related metadata.
• Both PUSH and PULL origins are supported.

Live stream lifecycle:

For live streams, type: stream webhooks can be sent at different stages of the stream lifecycle:

Stage	live/backup_live	transcoding	recording	Description
Primary ingest starts	true	false	false	Primary source connects; ingest is active, but playback might still be preparing, users will see 404 still.
Transcoding starts	true	true	false	Playback output is ready with status 200 OK; use this stage to show or activate a player for users.
Recording starts	true	true	true	The live stream is being recorded.
Stream stops	false	false	false	Final stage: the stream source disconnects or the broadcast ends, so the stream is not active.

Use live: true (or backup_live: true) to track active ingest. Use transcoding: true to track when the live stream is ready for playback.

Read more in the article Ingest & Backup.

Fields:

Field	Type	Description
id	int	Unique identifier of the stream
live	bool	true if the stream is currently active, false if it has stopped
backup_live	bool	true if the backup source is currently active
recording	bool	true if the stream is being recorded
transcoding	bool	true if transcoding has started and playback output is ready, false by default
client_user_id	string	Optional client-defined user ID, null if not provided
client_entity_data	string	Optional client metadata associated with the stream, null if not provided
pull	bool	true if the stream is pulled from an external origin, false if pushed
uri	string	The source URI of the stream:
stream_source_type	string	Type of the stream source: rtmp, srt, webrtc, https

Example:

Stream is ready for playback:

{
  "type": "stream",
  "message": {
    "stream": {
      "id": 1001,
      "live": true,
      "backup_live": false,
      "recording": false,
      "client_user_id": 10000001,
      "client_entity_data": "{ 'seq_id': '1234567890', 'name': 'John Doe', 'iat': 1516239022 }",
      "pull": false,
      "uri": "srt://vp-push-ed1-srt.gvideo.co:5001?streamid=12345#aaabbbcccddd",
      "stream_source_type": "srt",
      "transcoding": true
    }
  }
}

Stopped stream:

{
  "type": "stream",
  "message": {
    "stream": {
      "id": 1002,
      "live": false,
      "backup_live": false,
      "recording": false,
      "client_user_id": 10000001,
      "client_entity_data": "{ 'seq_id': '1234567890', 'name': 'John Doe', 'iat': 1516239022 }",
      "pull": true,
      "uri": "https://.../master.m3u8",
      "stream_source_type": "https",
      "transcoding": false
    }
  }
}

Webhooks for VOD

VOD webhooks use type: video for create and status updates, and type: video_delete when a video is deleted.

Webhook type	Status	Description
video	empty	Video entity is created, but the source file is still being received.
video	pending	Source file has been received and is being transcoded.
video	viewable	Playback is already available (not all qualities and codecs are ready, so transcoding is still ongoing).
video	ready	All qualities and codecs are processed and available for playback.
video	error	Upload or processing failed; check the error field.
video_delete	Current video status	Video entity was deleted.

Read more about VOD statuses in Video Lifecycle and Statuses.

VOD create and update

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.

Behavior:

• 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:

Field	Type	Description
id	int	VideoID
slug	string	Public identifier used in playback URLs
name	string	Video name
duration	int	Duration of the video in milliseconds
stream_id	int | null	StreamID if it was recorded from a Live stream, otherwise null
status	string	Processing status of the video: empty, pending, viewable, ready, error
converted_videos	array	List of transcoded renditions with details
└─ name	string	Rendition label (e.g., vod1080p)
└─ status	string	Rendition status
└─ mp4_url	string	Direct URL for a rendition in MP4 fromat

See the statuses of VOD processing in API docs:

• Video status processing – status
• Rendition status processing – converted_videos/status

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

VOD delete

A webhook with type video_delete notify your system that a VOD entity was deleted so you can purge caches, revoke URLs, and clean metadata.

Behavior:

• Fired when a video is deleted via API or UI.
• Emitted once per deletion event.

Fields:

Field	Type	Description
id	integer	VideoID
slug	string	Public identifier used in playback URLs
name	string	Video name
status	string	Processing status of the video
deleted_at	timestamp	ISO-8601 UTC timestamp of when the deletion was committed in the system

Example:

{
  "type": "video_delete",
  "message": {
    "video": {
      "id": 2001,
      "slug": "bJkptcIp9a5wrowz",
      "name": "football_videoplayback_720",
      "status": "ready",
      "deleted_at": "2025-09-16T13:50:42.000Z"
    }
  }
}

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.

Stage	live	Description
Restream starts	true	Restream is active and sends the source live stream to the destination.
Restream stops	false	Final stage: restream is not active and no longer sends content to the destination.

Behavior:

• Fired whenever a restream goes live or stops.
• Allows you to track the status of a specific restream linked to a live stream.

Fields:

Field	Type	Description
id	int	Unique identifier of the restream.
name	string	Human-readable name of the restream.
stream_id	int	ID of the source live stream that this restream is linked to.
live	bool	true 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 [e-mail] 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.

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.