The intent of this repository is to collect a list of reference implementations for webhook receivers that handle notifications from SUSE Studio, both for the hosted online and Onsite versions.
Webhooks are HTTP callbacks, often used for push notifications. Using webhooks to integrate your application or environment with SUSE Studio, one avoids the need to keep polling for changes. Instead, SUSE Studio contacts you via HTTP POST at the specified URL whenever an event occurs, with full details in the request body so that you can filter and process each notification accordingly. Refer to SUSE Studio's webhooks documentation for more details.
Each reference implementation in this repository (there's only one at the moment) is described below.
This Webhook receiver is written in Ruby with the Sinatra framework, both chosen for their simplicity and conciseness.
This receiver automatically imports all new 'SUSE Cloud / OpenStack / KVM' builds to your SUSE Cloud / OpenStack instance. It does so by listening for all 'build_finished' events that have the 'kvm' image type and importing that. Everything else is ignored.
Firstly, install the required Ruby dependencies:
sudo zypper in ruby rubygem-bundler
bundle install
You should then be able to run the script, at least to display the usage help:
> ./webhook-receiver-SUSE_Cloud.rb --help
Next, download the openrc.sh credentials file from your SUSE
Cloud /
OpenStack instance from "Settings" => "OpenStack
Credentials" => "Download RC File".
You also need to install the glance client. The following commands are for SLE11 SP2:
sudo su -
zypper addrepo \
http://download.opensuse.org/repositories/Cloud:/OpenStack:/Essex/SLE_11_SP2/ \
Virt:Cloud
zypper addrepo \
http://download.opensuse.org/repositories/devel:/languages:/python/SLE_11_SP2/ \
Devel:Languages:Python
zypper install python-glanceclient python-argparse
At this point, you should test that the manual import works. You can refer to our blog post for details on how to do that.
You must source the openrc.sh script (described in the previous section) and
enter the password before running the webhook receiver script, otherwise the
import to SUSE Cloud / OpenStack will fail. For example:
> . openrc.sh
Please enter your OpenStack Password:
Then run the receiver script from the same terminal:
> ./webhook-receiver-SUSE_Cloud.rb
Which should produce output similar to this:
[2012-10-08 15:37:41] INFO WEBrick 1.3.1
[2012-10-08 15:37:41] INFO ruby 1.9.3 (2012-04-20) [x86_64-linux]
== Sinatra/1.3.3 has taken the stage on 4567 for development with backup from WEBrick
[2012-10-08 15:37:41] INFO WEBrick::HTTPServer#start: pid=28396 port=4567
It defaults to listening on port 4567. If you are using Studio Online (http://susestudio.com), then the host running the webhook receiver and corresponding port must be publicly reachable. For security, you can whitelist requests from susestudio.com (130.57.70.200) in your firewall. Similarly if you are using Studio Onsite, the webhook receiver must be reachable by the Onsite instance.
There are a number of command line options that you can configure (inherited from Sinatra):
> ./webhook-receiver-SUSE_Cloud.rb --help
Usage: webhook-receiver-SUSE_Cloud [options]
-p port set the port (default is 4567)
-o addr set the host (default is 0.0.0.0)
-e env set the environment (default is development)
-s server specify rack server/handler (default is thin)
-x turn on the mutex lock (default is off)
All requests are logged to webhooks.log by default. You can change this by
changing the following line in the webhook receiver script accordingly:
env['rack.logger'] = Logger.new('webhooks.log')
Sample request log:
I, [2012-10-05T18:32:02.545621 #4442] INFO -- : Processing request {"payload"=>{"event"=>"build_finshed", "id"=>"24", "name"=>"My appliance", "build"=>{"id"=>"11", "version"=>"0.0.1", "image_type"=>"kvm", "image_size"=>"645", "compressed_image_size"=>"140", "download_url"=>"http://susestudio.com/download/f79d576ed150a0b877462fc0b3dcb92f/My_appliance.x86_64-0.0.1.oem.tar.gz", "md5"=>"f79d576ed150a0b877462fc0b3dcb92f"}}}
Sample log for ignored notifications (in this case, we only handle the 'kvm' image types):
I, [2012-10-08T13:52:40.915470 #22935] INFO -- : Ignored image type 'oem'
Sample log for a successful import:
I, [2012-10-08T13:58:45.587259 #23329] INFO -- : Processing request {"payload"=>{"event"=>"build_finished", "id"=>"24", "name"=>"Webhooks Test", "build"=>{"id"=>"11", "version"=>"0.0.1", "image_type"=>"kvm", "image_size"=>"645", "compressed_image_size"=>"140", "download_url"=>"http://bit.ly/UHn5C7", "md5"=>"f79d576ed150a0b877462fc0b3dcb92f"}}}
I, [2012-10-08T13:58:45.587685 #23329] INFO -- : Running command: glance --insecure image-create --name="Webhooks Test" --is-public=True --disk-format=qcow2 --container-format=bare --copy-from "http://bit.ly/UHn5C7" 2>&1
I, [2012-10-08T13:58:46.933713 #23329] INFO -- : Output:
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | 60f88f23a860a4fa05978209072ae64d |
| container_format | bare |
| created_at | 2012-10-08T14:00:34.663139 |
| deleted | False |
| deleted_at | None |
| disk_format | qcow2 |
| id | 260d3d89-c00f-4f3d-9e03-353544809a3d |
| is_public | True |
| min_disk | 0 |
| min_ram | 0 |
| name | Webhooks Test |
| owner | 25c05b2282c84622bc9a0db422664c96 |
| protected | False |
| size | 188 |
| status | active |
| updated_at | 2012-10-08T14:00:35.209841 |
+------------------+--------------------------------------+
I, [2012-10-08T13:58:46.933881 #23329] INFO -- : Import succeeded
You can mimic a webhook notification from Studio by running the following in the command line (change the values as needed):
curl -i -X POST \
-d 'payload[event]=build_finished' \
-d 'payload[id]=24' \
-d 'payload[name]=Webhooks Test' \
-d 'payload[build][id]=11' \
-d 'payload[build][version]=0.0.1' \
-d 'payload[build][image_type]=kvm' \
-d 'payload[build][image_size]=645' \
-d 'payload[build][compressed_image_size]=140' \
-d 'payload[build][download_url]=http://bit.ly/UHn5C7' \
-d 'payload[build][md5]=f79d576ed150a0b877462fc0b3dcb92f' \
'http://localhost:4567/'
Please send your feedback and bug reports to [email protected]. Pull requests are very much welcomed.