API Reference

Receiving Webhooks

After completing the previous tutorials, you learned to encode videos and create cool video previews. Finally, we saw how to submit the config file to be processed using the official client libraries.

In this final tutorial, we will explain how to retrieve the media URLs and errors from the webhook sent to your application when everything is complete.

The whole config file

For our tutorial, we will use an improved config file which combines everything we have seen previously:

# Variable declarations
var post = abc1234
var num = 3
var filename = demo

# AWS S3 bucket where the media will be uploaded
var access_key = accesskey
var secret_key = secretkey
var bucket = mybucket
var s3 = s3://$access_key:$secret_key@$bucket/$post

# Setting the source video and the webhook URL
set source = http://media.s3.amazonaws.com/demo.mp4
set webhook = http://yourserver.com/webhooks/coconut?post_id=$post

# Encoding for web and mobile devices
-> mp4 = $s3/videos/web/$filename.mp4
-> webm = $s3/videos/web/$filename.webm
-> mp4:360p = $s3/videos/mobile/$filename.mp4
-> httpstream = $s3, hls=$s3/videos/hls/, playlist_name=$filename

# Creating video previews
-> jpg:200x = $s3/thumbnails/small/$filename_#num#.jpg, number=$num
-> jpg:640x = $s3/thumbnails/large/$filename_#num#.jpg, number=$num
-> gif:300x = $s3/gif/$filename.gif
-> storyboard:640x = $s3/storyboard/$filename.png

After submitting this config file, we only need to wait for the webhook that would tell us that the whole job is done.

The Webhook

A webhook request is just a regular POST HTTP request in JSON format.

There are two fields that interest us: output_urls and errors. As you can guess, the first gives us all the media URLs and the latter, all the encountered errors.

Here is the sample JSON data based on our config file:

  "id": 1234,
  "output_urls": {
    "mp4": "http://mybucket.s3.amazonaws.com/abc1234/videos/mp4/demo.mp4",
    "mp4:360p": "http://mybucket.s3.amazonaws.com/abc1234/videos/mobile/demo.mp4",
    "httpstream": {
      "hls": "http://mybucket.s3.amazonaws.com/abc1234/videos/hls/demo.m3u8"
    "jpg:200x": [
    "jpg:640x": [
    "storyboard:640x": "http://mybucket.s3.amazonaws.com/abc1234/storyboard/demo.png"
  "errors": {
    "output": {
      "webm": "output_audio_cant_be_resampled",
      "gif:300x": "gif_not_uploaded"
  "event": "job.completed"

Awesome, every URLs and errors are there!

output_urls and errors are Hashes with each key corresponding to a section name used in the config file.

Writing the server

To receive webhooks, you just need to write the code listening to POST requests made to /webhooks/coconut (mentioned in the config file).

Exposing localhost to the Internet

While developing on your machine, your web app is not public and is thus not accessible by the Coconut servers. To make your local app reachable, we suggest to use ngrok.

Let's setup a small sinatra app to handle incoming webhooks:

# server.rb

require "sinatra"
require "json"

post "/webhooks/coconut" do
  urls = JSON.parse(request.body.read)["output_urls"]
  puts "Here are the media URLs: #{urls.inspect}"

Testing it:

ruby server.rb
[2014-04-08 16:47:14] INFO  WEBrick 1.3.1
[2014-04-08 16:47:14] INFO  ruby 2.1.1 (2014-02-24) [x86_64-darwin13.0]
== Sinatra/1.4.4 has taken the stage on 4567 for development with backup from WEBrick
[2014-04-08 16:47:14] INFO  WEBrick::HTTPServer#start: pid=74361 port=4567
Here are the media URLs: {"mp4"=>"http://mybucket.s3.amazonaws.com/abc1234/videos/mp4/demo.mp4", "ios:360p"=>"http://mybucket.s3.amazonaws.com/abc1234/videos/mobile/demo.mp4", "hls"=>"http://mybucket.s3.amazonaws.com/abc1234/videos/hls/demo.m3u8", "jpg:200x"=>["http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_01.jpg", "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_02.jpg", "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_03.jpg"], "jpg:640x"=>["http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_01.jpg", "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_02.jpg", "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_03.jpg"], "storyboard:640x"=>"http://mybucket.s3.amazonaws.com/abc1234/storyboard/demo.png"}
::1 - - [08/Apr/2014 16:47:17] "POST /webhooks/coconut HTTP/1.1" 200 - 0.0080
localhost - - [08/Apr/2014:16:47:16 CEST] "POST /webhooks/coconut HTTP/1.1" 200 0
- -> /webhooks/coconut

Excellent! You can do everything you need like saving the URLs into your database.

If you are a PHP guy, you might be interested in this sample code:

$body = file_get_contents("php://input");
$webhook = json_decode($body, true);

echo "Here are the media URLs:";

Congratulations! You have learned everything you need to know on how to integrate Coconut. Visit our FAQ or contact us if you have any questions.