Get webhooks from the video streaming

A webhook is a free automated notification about an event in our service. You can receive notifications about the following events of our Video Streaming:

• A live stream has started or finished.
• Recording of a live stream has started or paused.
• Updates on processing of a live stream recording: a recording has started processing, partially processed, or completely processed.
• Updates on broadcast statuses: pending, live, paused, or finished.
• A video is uploaded to the Gcore Customer Portal.
• Updates on video processing: a video has started processing, partially processed, or completely processed.
• Updates to a restream: it was created, is live, or was stopped.

Whenever any of these events happens, our server will create an HTTP POST request and notify you about it. You will receive the information in JSON format. Below is an example of a webhook triggered when a live stream starts.

{   
    "type": "stream",   
     "message": {   
           "stream": {   
             "id": 12345,   
             "live": true,  
             "recording": false    
           }   
      }   
}

Customize the following values:

• 12345 is the stream ID in the Gcore Customer Portal,
• true is the indicator that the Video Streaming is receiving your stream,
• false is the indicator that your stream is not being recorded.

What are the video streaming webhooks used for?

Webhooks are used by apps integrated with the Video Streaming. You can configure your app so that it will activate automatic workflows whenever it receives a webhook.

For example, users share videos in your app. When a user adds a new video, it is uploaded and processed through our Video Streaming. Then you need to embed the video in your application. You set up the auto-posting: as soon as the video is processed, the Video Streaming will send a webhook, and your app will post the video.

Configure the webhook integration

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.

We deliver webhooks for free from the IP range 92.223.123.0/24.

We can send webhooks of one account only to one server. If your server is unavailable, undelivered webhooks won’t be sent again. You will only receive a webhook of the next event.

Webhook examples of all video streaming events

Below are examples of all the webhooks that you can get from our service. Parameters are explained in round brackets.

A live stream has started

{   
  "type": "stream",   
  "message": {   
    "stream": {   
      "id": 12345,   
      "live": true,   
      "recording": false   
    }   
  }   
}

Where:

• 12345 is the stream ID in Gcore Customer Portal,
• true is the indicator that the Video Streaming is receiving your stream,
• false is the indicator that your stream is not being recorded.

A live stream is paused

{   
  "type": "stream",   
  "message": {   
    "stream": {   
      "id": 12345,   
      "live": false,   
      "recording": false   
    }   
  }   
} 

Where:

• 12345 is the stream ID in the Gcore Customer Portal,
• false is the indicator the Video Streaming is not receiving your stream,
• false is the indicator that your stream is not being recorded.

Recording has started

{  
  "type": "stream",   
  "message": {   
    "stream": {   
      "id": 12345,   
      "live": true,   
      "recording": true  
    }   
  }   
}

Where:

• 12345 is the stream ID in the Gcore Customer Portal,
• true is the indicator that the Video Streaming is receiving your stream,
• true is the indicator that your stream is being recorded.

Recording has finished

{   
  "type": "stream",   
  "message": {   
    "stream": {   
       "id": 12345,   
       "live": true,   
       "recording": false  
    }   
  }   
}

Where:

• 12345 is the stream ID in the Gcore Customer Portal,
• true is the indicator that the Video Streaming is receiving your stream,
• false is the indicator that your stream is not being recorded.

A recording has started processing

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 12345,   
      "slug": "ZeC44gtQQ4E97N9S",   
      "name": "Stream Record: test, 2022-05-27 09:08:40 +0000",   
      "duration": 19580,   
      "status": "pending",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "processing"  
        },   
        {            
           "name": "vod480n",   
           "status": "processing"   
        },   
        {   
          "name": "vod360n",   
          "status": "processing"   
        },   
        {   
           "name": "vod240n",   
           "status": "processing"   
        }   
      ]    
    }   
  }   
}

Where:

• 12345 is the recording ID in the Gcore Customer Portal,
• ZeC44gtQQ4E97N9S is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• test is your stream name,
• 19580 is the recording duration in seconds,
• vod720n, vod480n, vod360n, vod240n are the different qualities of the record.
• processing is indicator that the recording is being processed.

A recording is partially processed

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 12345,   
      "slug": "ZeC44gtQQ4E97N9S",   
      "name": "Stream Record: test, 2022-05-27 09:08:40 +0000",   
      "duration": 19580,   
      "status": "viewable",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "complete"   
        },   
        {   
          "name": "vod480n",   
          "status": "processing"   
        },   
        {   
          "name": "vod360n",   
          "status": "processing"   
        },   
        {   
          "name": "vod240n",    
          "status": "processing"   
        }   
      ]   
    }   
  }   
}

Where:

• 12345 is the recording ID in the Gcore Customer Portal,
• ZeC44gtQQ4E97N9S is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• test is your stream name,
• 19580 is the recording duration in seconds,
• vod720n, vod480n, vod360n, vod240n are the different qualities of the record.
• processing is indicator that the recording is being processed.
• complete is the indicator that the processing is completed.

A recording is completely processed

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 12345,   
      "slug": "ZeC44gtQQ4E97N9S",   
      "name": "Stream Record: test, 2022-05-27 09:08:40 +0000",   
      "duration": 19580,   
      "status": "ready",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "complete"   
        },   
        {   
           "name": "vod480n",   
           "status": "complete"   
        },  
        {   
          "name": "vod360n",   
          "status": "complete"  
        },   
        {   
          "name": "vod240n",    
          "status": "complete"    
        }   
      ]   
    }   
  }   
} 

Where:

• 12345 is the recording ID in the Gcore Customer Portal,
• ZeC44gtQQ4E97N9S is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• test is your stream name,
• 19580 is the recording duration in seconds,
• vod720n, vod480n, vod360n, vod240n are the different qualities of the record.
• complete is the indicator that the processing is completed.

A broadcast status is updated to “Waiting to start”

{   
  "type": "broadcast",   
  "message": {   
    "broadcast": {   
      "id": 12345,   
      "status": "pending"   
    }   
  }   
}

Where:

• 12345 is the broadcast ID in your personal account,
• pending is the status which means “Waiting to start”.

A broadcast status is updated to “Live”

{   
  "type": "broadcast",   
  "message": {   
    "broadcast": {   
      "id": 12345,   
      "status": "live"   
    }   
  }   
}

Where:

• 12345 is the broadcast ID in your personal account,
• live is the status which means “Live”.

A broadcast status is updated to “Finished”

{   
  "type": "broadcast",   
  "message": {   
    "broadcast": {   
      "id": 12345,   
      "status": "finished"   
    }   
  }   
}

Where:

• 12345 is the broadcast ID in your personal account,
• finished is the status which means “Finished”.

A broadcast status is updated to “Paused”

{   
  "type": "broadcast",   
  "message": {   
    "broadcast": {   
      "id": 12345,   
      "status": "paused"  
    }   
  }   
}

Where:

• 12345 is the broadcast ID in your personal account,
• paused is the status which means “Paused”.

A video is uploaded to the Video Streaming

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 54321,   
      "slug": "Lfsq14hKvLkNsExx",   
      "name": "SampleVideo",   
      "duration": 170859,   
      "status": "empty",   
      "converted_videos": []   
    }   
  }   
}  

Where:

• 54321 is the video ID in the Gcore Customer Portal,
• Lfsq14hKvLkNsExx is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• SampleVideo is the video name,
• 170859 is the duration of the video in seconds,
• empty is the status which means that the video has not been processed yet

A video has started processing

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 784280,   
      "slug": "Lfsq14hKvLkNsExx",   
      "name": "SampleVideo",   
      "duration": 170859,   
      "status": "pending",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "processing"   
        },   
        {   
          "name": "vod480n",   
          "status": "processing"   
        },   
        {   
          "name": "vod360n",   
          "status": "processing"   
        },   
        {   
          "name": "vod240n",   
          "status": "processing"  
        }   
      ]   
    }   
  }   
}

Where:

• 784280 is the video ID in the Gcore Customer Portal,
• Lfsq14hKvLkNsExx is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• SampleVideo is the video name,
• 170859 is the duration of the video in seconds,
• processing, pending are the different statuses of the video processing.
• vod720n, vod480n, vod360n, vod240n are the different qualities of the video.

A video is partially processed

{   
  "type": "video",   
  "message": {   
    "video": {   
      "id": 784280,   
      "slug": "Lfsq14hKvLkNsExx",   
      "name": "SampleVideo",   
      "duration": 170859,   
      "status": "viewable",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "complete"   
        },   
        {   
          "name": "vod480n",   
          "status": "processing"  
        },   
        {   
          "name": "vod360n",   
          "status": "processing"   
        },   
        {   
          "name": "vod240n",   
          "status": "processing"  
        }   
      ]   
    }   
  }  
}

Where:

• 784280 is the video ID in the Gcore Customer Portal,
• Lfsq14hKvLkNsExx is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• SampleVideo is the video name,
• 170859 is the duration of the video in seconds,
• processing, complete, viewable are the different statuses of the video processing.
• vod720n, vod480n, vod360n, vod240n are the different qualities of the video.

A video is completely processed

{   
  "type": "video",  
  "message": {   
    "video": {   
      "id": 784280,   
      "slug": "Lfsq14hKvLkNsExx",   
      "name": "SampleVideo",   
      "duration": 170859,   
      "status": "ready",   
      "converted_videos": [   
        {   
          "name": "vod720n",   
          "status": "complete"   
        },   
        {   
          "name": "vod480n",   
          "status": "complete"   
        },   
        {   
          "name": "vod360n",   
          "status": "complete"   
        },   
        {   
          "name": "vod240n",   
          "status": "complete"   
        }   
      ]   
    }   
  }  
}

Where:

• 784280 is the video ID in the Gcore Customer Portal,
• Lfsq14hKvLkNsExx is the video ID presented as a random set of characters, which prevents a video URL from stealing if the webhook is intercepted,
• SampleVideo is the video name,
• 170859 is the duration of the video in seconds,
• complete, ready is the status which means that the video was processed.
• vod720n, vod480n, vod360n, vod240n are the different qualities of the video.

A restream was created

{ 
  "type": "restream", 
  "message": { 
    "restream": { 
      "id": 228237, 
      "name": "restream 1", 
      "stream_id": 1665243, 
      "live": true 
      "active": false 
    } 
  }
}

Where:

• 228237 is the restream ID in Gcore Customer Portal
• restream 1 is the name of your restream
• 1665243 is the stream ID in Gcore Customer Portal
• true is the indicator that the Video Streaming is receiving your restream
• false is the indicator that your stream is not being broadcasted

A restream is live

{ 
  "type": "restream", 
  "message": { 
    "restream": { 
      "id": 228237, 
      "name": "restream 1", 
      "stream_id": 1665243, 
      "live": true 
    } 
  } 
} 

Where:

• 228237 is the restream ID in Gcore Customer Portal
• restream 1 is the name of your restream
• 1665243 is the stream ID in Gcore Customer Portal
• true is the indicator that the Video Streaming is receiving your restream

A restream was stopped

{ 
  "type": "restream", 
  "message": { 
    "restream": { 
      "id": 228237, 
      "name": "restream 1", 
      "stream_id": 1665243, 
      "active": false 
    } 
  } 
} 

Where:

• 228237 is the restream ID in Gcore Customer Portal
• restream 1 is the name of your restream
• 1665243 is the stream ID in Gcore Customer Portal
• false is the indicator that your stream is not being broadcasted