POST service webhook for Bitbucket Server

Repository administrators can add a POST service to a repository. Bitbucket Server POSTs to the service URL you specify.

You can use an URL with the following format:

https://server:port/path/

The service receives a POST whenever the user pushes to the repository.

The content type header of the POST has an application/json type. The content is a JSON payload that represents the repository push.

Setting up the POST service

You can either set up the POST service manually or you can write a service to automate this. You would write a service if you are integrating an application with Bitbucket Server.

Set up in the repository settings

  1. Go to the repository's settings.
  2. Click Hooks in the left-hand navigation.
  3. Click Enable for the 'Post-Receive Webhooks' item. You can add up to 5 URLs for where Bitbucket Server should send its update messages.
  4. Press Save.

POST data

When a user pushes to a repository, Bitbucket Server POSTs to the URL you provided. The body of the POST request contains information about the repository where the change originated, a list of recent commits, and the name of the user that made the push. 

Example of payload

This is an example of a push that contains one commit that changes 2 files (pom.xml) in folders iridium-common and iridium-magma.

JSON Payload
{
   "repository":{
      "slug":"iridium-parent",
      "id":11,
      "name":"iridium-parent",
      "scmId":"git",
      "state":"AVAILABLE",
      "statusMessage":"Available",
      "forkable":true,
      "project":{
         "key":"IR",
         "id":21,
         "name":"Iridium",
         "public":false,
         "type":"NORMAL",
         "isPersonal":false
      },
      "public":false
   },
   "refChanges":[
      {
         "refId":"refs/heads/master",
         "fromHash":"2c847c4e9c2421d038fff26ba82bc859ae6ebe20",
         "toHash":"f259e9032cdeb1e28d073e8a79a1fd6f9587f233",
         "type":"UPDATE"
      }
   ],
   "changesets":{
      "size":1,
      "limit":100,
      "isLastPage":true,
      "values":[
         {
            "fromCommit":{
               "id":"2c847c4e9c2421d038fff26ba82bc859ae6ebe20",
               "displayId":"2c847c4"
            },
            "toCommit":{
               "id":"f259e9032cdeb1e28d073e8a79a1fd6f9587f233",
               "displayId":"f259e90",
               "author":{
                  "name":"jhocman",
                  "emailAddress":"jhocman@atlassian.com"
               },
               "authorTimestamp":1374663446000,
               "message":"Updating poms ...",
               "parents":[
                  {
                     "id":"2c847c4e9c2421d038fff26ba82bc859ae6ebe20",
                     "displayId":"2c847c4"
                  }
               ]
            },
            "changes":{
               "size":2,
               "limit":500,
               "isLastPage":true,
               "values":[
                  {
                     "contentId":"2f259b79aa7e263f5829bb6e98096e7ec976d998",
                     "path":{
                        "components":[
                           "iridium-common",
                           "pom.xml"
                        ],
                        "parent":"iridium-common",
                        "name":"pom.xml",
                        "extension":"xml",
                        "toString":"iridium-common/pom.xml"
                     },
                     "executable":false,
                     "percentUnchanged":-1,
                     "type":"MODIFY",
                     "nodeType":"FILE",
                     "srcExecutable":false,
                     "link":{
                        "url":"/projects/IR/repos/iridium-parent/commits/f259e9032cdeb1e28d073e8a79a1fd6f9587f233#iridium-common/pom.xml",
                        "rel":"self"
                     }
                  },
                  {
                     "contentId":"2f259b79aa7e263f5829bb6e98096e7ec976d998",
                     "path":{
                        "components":[
                           "iridium-magma",
                           "pom.xml"
                        ],
                        "parent":"iridium-magma",
                        "name":"pom.xml",
                        "extension":"xml",
                        "toString":"iridium-magma/pom.xml"
                     },
                     "executable":false,
                     "percentUnchanged":-1,
                     "type":"MODIFY",
                     "nodeType":"FILE",
                     "srcExecutable":false,
                     "link":{
                        "url":"/projects/IR/repos/iridium-parent/commits/f259e9032cdeb1e28d073e8a79a1fd6f9587f233#iridium-magma/pom.xml",
                        "rel":"self"
                     }
                  }
               ],
               "start":0,
               "filter":null
            },
            "link":{
               "url":"/projects/IR/repos/iridium-parent/commits/f259e9032cdeb1e28d073e8a79a1fd6f9587f233#iridium-magma/pom.xml",
               "rel":"self"
            }
         }
      ],
      "start":0,
      "filter":null
   }
}

Properties

Some of the system-wide properties for the Webhook Plugin can be overridden in the Bitbucket Server configuration file. The available properties are listed in Bitbucket Server config properties.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport