We provide the option to communicate with a web server whenever a video is done processing using webhooks.

Table of Contents

Adding a Webhook

There are two ways to enable a webhook to be triggered when your videos are deployed.

Account-Wide Webook

Use this method when you want all of your videos to use the same webhook:

  1. Log in to your account and move your mouse over the person icon in the top right and click ‘Account Settings’ in the dropdown menu.
  2. Click on the ‘API’ tab
  3. Enter your URL in the Webhook URL and click Update Video Setting.

Per-Video Webhook

You can use a different webhook for every video if you use the notification_url input when uploading a video through the Sproutvideo API.

The Payload

When a video is done processing, we’ll POST to your URL with a payload of JSON-encoded data about the video. Here is an example of the result:

  "id": "a098d2bbd33e1c328",
  "width": 1280,
  "height": 720,
  "embed_code": "<iframe class='sproutvideo-player' src='https://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>",
  "source_video_file_size": 29257997,
  "sd_video_file_size": 0,
  "hd_video_file_size": 0,
  "security_token": "7ca00d6d622a8e8d",
  "title": "A new video",
  "description": "This is an example video",
  "duration": 140.334,
  "privacy": 2,
  "password": null,
  "state": "deployed",
  "tags": [

  "created_at": "2023-06-28T19:50:49Z",
  "updated_at": "2023-06-28T19:51:29Z",
  "plays": 0,
  "progress": 100,
  "requires_signed_embeds": null,
  "selected_poster_frame_number": 0,
  "embedded_url": null,
  "assets": {
    "videos": {
      "240p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/240.mp4",
      "360p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/360.mp4",
      "480p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/480.mp4",
      "720p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/720.mp4",
      "1080p": null,
      "2k": null,
      "4k": null,
      "8k": null,
      "source": null
    "thumbnails": [
    "poster_frames": [
    "poster_frame_mp4": null,
    "timeline_images": [
    "hls_manifest": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/index.m3u8"
  "download_sd": null,
  "download_hd": null,
  "download_uhd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "folder_id": null,
  "session_watermarks": null

This is sent as a POST as the POST body.

Verify webhook signatures

Webhooks contain a header called sproutvideo-signature with the timestamp and a signature. The timestamp is prefixed by t= and the signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid signature scheme is v1. SproutVideo generates signatures using HMAC with SHA2-256.

sproutvideo-signature: t=1687982892,v1=dyBKXhGwNKkd5xsctj6F7eYU8/y+Op2tBnq3Aj0mj+4=

1. Extract the timestamp and signature

Split the header at the , character and get the values for t (timestamp) and v1 (the signature)

2. Prepare the signed_payload string

You will need:

  • the timestamp from Step 1 as a string (for example: “1687982892”)
  • the dot character .
  • the raw request body (this will be JSON in a string format)

3. Determine the expected signature

Use the 3 components from Step 2 to compute an HMAC with the SHA256 hash function. Depending on the language that you are using this will look something like the following:

secret = 'my api key' // your api key
payload = timestamp + "." + request_body
expected_signature = createHmacSha256(payload, secret)

4. Compare signature

Compare the signature in the header to the expected signature. If the signature matches, compute the difference between the current timestamp and the received timestamp, then check to make sure that the timestamp is within our tolerance. A good starting point is 5 minutes.


We recommend using RequestBin to troubleshoot WebHooks.

Was this article helpful?