JSON webhook

If you would like to start baking an AMI by sending a request to a URL, this is the page for you.

By POSTing a JSON object to the "Generic JSON Webhook URL" for a Build Pipeine, a new Bake will be started.

    ┌──────────────────┐                 ┌──────────────────┐   
    │                  │                 │                  │   
    │    Your code     │──────JSON──────▶│      Bakery      │   
    │                  │                 │                  │   
    └──────────────────┘                 └──────────────────┘   
 ║                                                 │           ║
 ║                                                 ▼           ║
 ║                                       ┌──────────────────┐  ║
 ║                                       │                  │  ║
 ║                                       │    Bake #123     │  ║
 ║                                       │                  │  ║
 ║                                       └──────────────────┘  ║
 ║                                                 │           ║
 ║                                                 ▼           ║
 ║                                            ┏━━━━━━━━┓       ║
 ║                                            ┃        ┃       ║
 ║                                            ┃  AMI   ┃       ║
 ║                                            ┃        ┃       ║
 ║                                            ┗━━━━━━━━┛       ║
 ║                      Your AWS Account                       ║

Diagram drawn using Monodraw.

Where is the "Generic JSON Webhook URL"?

Once you have a Build Pipeline configured in the Bakery, the JSON Webhook URL will be on the details page under the Continuous Integration section. The URL will look something like this:


This is the URL to POST to.

What do I POST?

As you might imagine, the structure of the JSON is important. Here is an example:

  "name": "My Cool Script",
  "url": "http://example.com/my-cool-script.newhotness",
  "build": {
    "full_url": "http://service.example.com/app/build/1337",
    "build_id": "1337",
    "status": "success",
    "scm": {
      "url": "git@github.com:example/my-repo.git",
      "branch": "origin/master",
      "commit": "c715aae9bdbc3179c6fd0007c8089ca150ff7dc0"
    "artifacts": {
      "my-app.war": {
        "s3": "https://s3-us-west-2.amazonaws.com/artifacts/my-app.war"


  • name: String Required
    • The human friendly name of the script POSTing to the webhook.
  • url: String Optional
    • The URL of the calling script.
  • build: JSON Oject Required
    • Generally, the webhook will be called when a specific build or version is ready to Bake. This JSON object has those details.
  • build/full_url: String Optional
    • If the build was trigged by some CI server, then here is where you would put the full URL to the specific build.
  • build/build_id: String Optional
    • A build usually has some kind of ID, perhaps a build number if being triggered by a CI tool.
  • build/status: String Required
    • Some build servers like to send notifications even when a build fails. In order for the Bakery to bake an AMI, the value of this field must be success.
  • build/scm: JSON Object Conditionally Optional
    • Either this or build/artifacts must be present.
    • If your code isn't compiled (Ruby, PHP, Javascript, etc), then the commit SHA is probably important as that is what you want to build from. Here is where you pass along that information.
  • build/scm/url: String Required
    • The URL (in either HTTPS or SSH format) of the repository to get your code from.
  • build/scm/branch: String Required
    • The branch the commit was on.
  • build/scm/commit: String Required
    • The ID of the commit - usually a SHA.
  • build/artifacts: JSON Object Conditionally Optional
    • If you do not specify a scm object, you need to specify this one
    • If your code is compiled (Go, Java, etc), rather than building something from source, you probably want to use the compiled build artifacts. This is the object for you.
  • build/artifact/NAME: JSON Object At least 1 is required
    • What you call this object is up to you. What you put in this object is also up to you. In your config management, you can reference this object and the fields within it. See below.

How do I use that JSON object in my config management?

Since the Bakery only supports Ansible right now, this is very easy.

In the Ansible playbook the Build Pipeline is using, you want to reference a vars_file called /tmp/bakery/webhook.yml. This makes all fields available inside your Ansible tasks. For example:

  - hosts: all
      - [ /tmp/bakery/webhook.yml, vars/defaults.yml ]
      - { role: myrole, tags: ['myrole'] }

Notice that the webhook.yml file is outside your playbooks directory. It is in the /tmp directory and therefore will not be part of your final AMI. Notice also that we are specifying a fallback in the form of vars/defaults.yml. The Bakery allows you to click a button to build an AMI. That's the beauty of it. It also means the JSON payload will not always be present, and the /tmp/bakery/webhook.yml file will not exist. To account for that, we recommend creating a vars/defaults.yml file inside your Ansible repo with some sensible default values.

The contents of webhook.yml is a direct YAML conversion of the JSON that was sent over. Following on from the above example, the YAML would be:

  name: "My Cool Script"
  url: "http://example.com/my-cool-script.newhotness"
    full_url: "http://service.example.com/app/build/1337"
    build_id: "1337"
    status: "success"
      url: "git@github.com:example/my-repo.git"
      branch: "origin/master"
      commit: "c715aae9bdbc3179c6fd0007c8089ca150ff7dc0"
        s3: "https://s3-us-west-2.amazonaws.com/artifacts/my-app.war"

To reference fields in your Ansible playbooks and roles, use Ansible variables. For example, getting the code for the specific commit, you might use a play like this:

  - name: Get the code from the git repo
      repo: "{{ build['scm']['url'] }}"
      dest: /var/www/myapp
      version: "{{ build['scm']['commit'] }}"
      accept_hostkey: yes

To download the my-app.war file from S3, the play might look like this:

  - name: Download artifact from S3
    command: aws s3 cp {{ build['artifacts']['my-app.war']['s3'] }} /apps/my-app.war

Full example

A complete example of how to use both the source control and artifact methods, please have a look at the json-webhook examples in the Bakery Examples repository on GitHub.


What do you think of this page? Tell us about it