Deploy Hooks on Workflow

16 Dec 2016

In January, we will be releasing Workflow v2.10.0. In this release, we will be introducing deploy hooks into Workflow. This feature allows administrators of the platform to add a list of HTTP endpoints that will receive POST requests when a new release of any application on the platform is pushed.

What are Deploy Hooks?

Deploy hooks allow an external service to receive a notification whenever a new version of an application is pushed to Workflow. It’s useful to help keep the development team informed about deploys, while it can also be used to integrate different systems together. Example systems that might make use of this could be a Slack plugin, an end-to-end test suite which runs when triggered, or any other service which responds to events.

When configured, the deploy hook performs an HTTP POST to a number of given URLs. The information sent to the external service would be any important information about the release, including the release summary, who created the release, the application this release is for, the release version number and (if applicable) the commit SHA of the release.

For example, if the controller has DEIS_DEPLOY_HOOK_URLS set to "https://example.com", the application is called secure-woodland, and Gabriel pushed a new version of the app to Workflow, the shipped POST request would look something like this:

https://example.com?app=secure-woodland&release=v4&release_summary=gabrtv%20deployed%35b3726&sha=35b3726&user=gabrtv

How can I Check the Deploy Hook Came from Workflow?

Deploy hooks are optionally configured to send a keyed-hash message authentication code (HMAC) in the Authorization header. You can configure the private key used to compute the HMAC signature by supplying a private key in the DEIS_DEPLOY_HOOK_SECRET_KEY environment variable.

To test that a request came from Workflow, we can use the secret key, the full URL and the HMAC-SHA1 hashing algorithm to compute the signature. In Python, that would look something like this:

import hashlib
import hmac

hmac.new("my_secret_key", "http://deis.rocks?app=secure-woodland&release=v4&release_summary=gabrtv%20deployed%35b3726&sha=35b3726&user=gabrtv", digestmod=hashlib.sha1).hexdigest()

If the value of the computed HMAC hex digest and the value in the Authorization header are identical, then the request came from Workflow.

When computing the signature, it is important to ensure that the URL parameters are in alphabetic order. This is critical when computing the cryptographic signature as most web applications don't care about the order of the HTTP parameters, but when dealing with generating cryptographic signatures, the devil is in the details.

Any Questions?

If you have any more questions about deploy hooks, we have documentation available on our website. Or, you can just raise an issue in GitHub and ask away on the #community channel on Slack at any time.

Posted in Deis Workflow

triangle square circle

Did you enjoy this post?