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:
- 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.
- Click on the ‘API’ tab
- 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": [ "https://images.sproutvideo.com/.../.../thumbnails/frame_0000.jpg", "https://images.sproutvideo.com/.../.../thumbnails/frame_0001.jpg", "https://images.sproutvideo.com/.../.../thumbnails/frame_0002.jpg", "https://images.sproutvideo.com/.../.../thumbnails/frame_0003.jpg", "https://images.sproutvideo.com/.../.../thumbnails/frame_0004.jpg", "https://images.sproutvideo.com/.../.../thumbnails/frame_0005.jpg" ], "poster_frames": [ "https://images.sproutvideo.com/.../.../poster_frames/frame_0000.jpg", "https://images.sproutvideo.com/.../.../poster_frames/frame_0001.jpg", "https://images.sproutvideo.com/.../.../poster_frames/frame_0002.jpg", "https://images.sproutvideo.com/.../.../poster_frames/frame_0003.jpg" ], "poster_frame_mp4": null, "timeline_images": [ "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/timeline_0000.jpg" ], "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.
Troubleshooting
We recommend using RequestBin to troubleshoot WebHooks.
Other articles in the Uploading section:
- How to Upload MP3 Audio Files to SproutVideo
- How to Clone a Video or Live Stream
- How to Import Videos from Dropbox, Google Drive, OneDrive, or Box
- What Formats Does SproutVideo Accept?
- How to Upload a Video, or Multiple Videos at One Time
- How Many Videos Can You Upload at One Time?
- How Large Can Your Videos Be?
