POST service management

Deprecation Notice

In the future, you will no longer be able to create a POST service from the Services screen, as Bitbucket’s updated webhooks will replace this service. Existing services will continue to function as expected for now.

To create a new webhook, refer to the webhooks documentation.

Repository administrators can add a POST service to a repository. Bitbucket POSTs to a service URL you specify. Bitbucket supports HTTPS and basic authentication. For example, you can use a URL in the format:

The POST request originates from the IP addresses described in our firewall information page. You may need to configure your firewall to accept connections from these IP addresses.

The service receives an POST whenever user pushes to the repository. The content header of the POST has an application/x-www-form-urlencoded type. This service behave similarly to an HTTP publish/subscribe service. The payload has payload= prepended to the actual payload. The payload is url encoded content.

Set up the POST service

You can set up the POST service manually or you can automate the creation of a service from your own application.

Manually from Repository Administration

  1. Go to the repository's  settings.
  2. Click Services in the left-hand navigation.
    The Services page appears.
  3. Select the POST service from the services dropdown.
  4. Click Add service.
    A new section appears for the POST service.
  5. Enter the URL where Bitbucket should send its update messages.

  6. Press Save.

Automatically fill in from another application

If you are integrating with Bitbucket and looking for an easy way to add the service for your users, there are two methods you can use to automate this.  You can send the user to a URL structured in the following way:

If you're using OAuth or passing through basic authentication, you can use the api to accomplish this as well

POST Data

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

Example

Mercurial
Git

If you are having trouble with the service, see  Troubleshooting Bitbucket services.

Was this helpful?

Thanks for your feedback!

55 Archived comments

  1. User avatar

    Anonymous

    I am looking for a possibility to parameterize the post-string with the highest branch number available in the bitbucket repository, something like http://localhost:8080/job/abc/build?branch=$\[highest-available-branch-number\].

    Whereby the vaule of $[highest-available-branch-number] is automatically calculated.

    Any suggestions?

    Maybe I could write my own custom Bitbucket POST service as a plugin, but how can I develop and deploy it?

    21 Jun 2011
  2. User avatar

    Andrew Elster

    Are there any plans to enable merged pull requests to trigger a POST?

    02 May 2012
  3. User avatar

    Stan Gogh

    Is there a way to see a log of the responses for these posts?  We are getting no notifications if the post fails.

    06 Jul 2012
    1. User avatar

      Marcus Bertrand [Atlassian]

      We don't have a public log, but if you open a support request to support@bitbucket.org we can help troubleshoot with you.

      06 Jul 2012
  4. User avatar

    Musti R

    Hello Atlassian,

    I need help for two questions:

    1. I cannot make the Post service to work on IIS 7 and ASP.NET I am using mercurial and TortoiseHG 2.42, I added the Post service and have the following url: localhost/default.aspx. I am expecting the page to show up when I push to the server but nothing happened. Any sample code for this to  make it working will be highly appreciated.
    2. My second question/help is that I am trying to use the Mercurial.net Library to do some HG operation such as pull, push, etc. is there a sample code also to show how to use the PullCommand and PushCommand as well it is very appreciated.

    Thanks

    Musti

    14 Aug 2012
    1. User avatar

      manthony

      Musti, please send an email to support@bitbucket.org with your questions. 

      14 Aug 2012
  5. User avatar

    Musti R

    Hello there,

    I am using mercurial_Keyring extension to store the password and running a console application to pull and update every 5 minutes. it works fine untill I switch to Amason. Using Amazon instance the password not always stored and it requires to enter the password, hence the application fails to pull and update. My question is there a way to store the password to be persistence or pass it as part of the bitbucket request in some sort?

    Thanks

    02 Oct 2012
  6. User avatar

    Stefán Freyr Stefánsson

    Why are the revision numbers in the POST data (for git pushes) always "null" and the size -1?

    Is there a way to find out whether the push resulted in a branch being deleted?

    23 Jan 2013
    1. User avatar

      manthony

      I'll have to do some research into your first question. Regarding the second, you could query for the branch using repo_slug Resource call.

      28 Jan 2013
      1. User avatar

        Stefán Freyr Stefánsson

        Thanks for your answer Mary.

        It seems to me that doing a GET query is a bit of an overkill. At least IMO the information should be in the POST data.

        Another issue that I just found out is that if a push affects one branch then the branch name is in a variable in the JSON data called "branch". However, if the push affects multiple branches, a variable called "branches" pops up out of nowhere and the "branch" variable is empty while the "branches" variable contains an array of the affected branches. First of all, this needs to be documented somewhere! Second, I just think this is bad form, the variable should just be named "branches" and contain a list of one branch or multiple branches. It's silly to have to check for both of them.

        28 Jan 2013
  7. User avatar

    Richard Barrell

    Is there a way to automatically set up a POST service for every single repository in an organisation, please? I'm in an organisation with more than 70 repositories and our workflow involves adding an average of at least one new repository every few months. It would be enormously inconvenient to have to set up the POST services for all of them manually, and doubly so to have to set the POST service up every single time we create/import another repo, since someone might miss one and then we'd end up with random workflow bugs.

    05 Apr 2013
    1. User avatar

      manthony

      We don't have a way to do this through the UI.  It sounds like for your use case a little client to do the "create repo" for your teams would be best.  You could use the repository Resource to create the repo and then call services Resource.

      05 Apr 2013
      1. User avatar

        Richard Barrell

        Ah, that will do nicely, thank you.

        05 Apr 2013
  8. User avatar

    Hean Hong Leong

    The value of "commits" is an array. Is it possible to have multiple commits per post-receive event?

    17 Apr 2013
    1. User avatar

      manthony

      Hean,

      The post receive hook runs in response to a push. So, a push can contain multiple commits yes.  You can create a service that parses the POST data and does something in response to each commit in the array.

      Mary

      19 Apr 2013
  9. User avatar

    Hean Hong Leong

    Thanks.

    20 Apr 2013
  10. User avatar

    Anonymous

    Which variable exactly houses the POST data in PHP?

    17 May 2013
    1. User avatar

      Anonymous

      I believe that would be the $_POST array in PHP.

      26 Jul 2013
      1. User avatar

        Anonymous

        $_POST['payload']

        07 Jan 2014
  11. User avatar

    Anonymous

    Why does the above POST data contain types like numbers, null and booleans? You state that the data is posted with application/x-www-form-urlencoded which only supports strings. Can I expect the values to be like "-1", "null" and "true"?

    22 May 2013
  12. User avatar

    Anonymous

    Which "type" attributes should I expect to see in the commit->files array?

    11 Jun 2013
    1. User avatar

      manthony

      The possible types are modified, added and removed.  

      11 Jun 2013
  13. User avatar

    Bruno Braga

    Have you changed your IP to 207.223.240.188? I am receiving posts now from this one instead!!! 

    12 Jun 2013
    1. User avatar

      Bruno Braga

      You guys should notify us before doing such changes... until someone realize this is happening, too many POSTs will be lost.

      Anyway, thanks for updating the IPs on this page.

      12 Jun 2013
  14. User avatar

    Davey Kulter

    Why am I still receiving POST requests from your old IP address as well as your new IP addresses?

    And why didnt you guys notify us of the IP change. It would seem rather important

    13 Jun 2013
    1. User avatar

      Anonymous

      The documentation above clearly states that the POST can now come from either IP address.

      Yes, they should have notified everybody, no question. They obviously screwed up. It would be nice to get an official statement from Atlassian.

      I somehow have the feeling that they are not really that dedicated to this POST interface, this being a perfect example and my question above about why the revision numbers are always null and the size always -1 which hasn't been answered. So please Atlassian, decide whether you're going to officially support this POST hook and then show it! People are starting to rely on this behavior and your processes aren't cutting it.

      13 Jun 2013
      1. User avatar

        Davey Kulter

        I dont see it saying that it can also come from their old IP address (63.246.22.222), I only see their two new IP addresses listed (207.223.240.187 and 207.223.240.188).

        Correct me if I am wrong.

        13 Jun 2013
  15. User avatar

    Charles McLaughlin [Atlassian]

    The IP address change was announced via our blog:

    http://blog.bitbucket.org/2013/06/11/new-outbound-ip-addresses-for-post-receive-hooks/

    Apologies for the short notice, but we are very unlikely to email all our users for these types of changes.  Please follow the blog rss feed for further updates and changes.  That's where we announce all scheduled maintenance and changes. 

    13 Jun 2013
  16. User avatar

    Anonymous

    You don't have to email all your users. It's not a difficult lookup to see what users have repositories that have this POST service method active is it?

    Please consider emailing the set of users that use the service you intend to change before making the change in the future.

    14 Jun 2013
  17. User avatar

    Anonymous

    Do pushed tags trigger POSTs? What does the payload look like? Does this happen when only a tag is pushed? What if the tag refers to commits that are not on a named branch?

    25 Jun 2013
  18. User avatar

    Anonymous

    As per http://blog.bitbucket.org/2013/07/02/scheduled-downtime-bitbucket-moves-data-centers-on-july-7/, outgoing IP addresses need to be updated to 131.103.20.165 and 131.103.20.166.

    08 Jul 2013
    1. User avatar

      manthony

      Thanks for the catch. Updated.

      08 Jul 2013
  19. User avatar

    Anonymous

    These examples need updating, this isn't what my listener receives from bitbucket. It seems to be invalid JSON too...

    15 Jul 2013
    1. User avatar

      manthony

      You are correct. I've added updating this to my list of tasks.  Thanks for the comments.

      17 Jul 2013
  20. User avatar

    Anonymous

    I found the documentation here to be misleading.  At least with node/restify, the body is a JSON object that has an element called payload, which contains an escaped string that then must be parsed.

    16 Jul 2013
    1. User avatar

      manthony

      When I do the update, I'll check this as well. Thanks for the comment.

      17 Jul 2013
      1. User avatar

        Vasilii Zolotukhin

        I confirm, payload requires a parsing

        08 Oct 2013
        1. User avatar

          Mick O'Hea

          Documentation is still incorrect, payload is still an escaped string

          26 Feb 2014
  21. User avatar

    Anonymous

    The link "https://bitbucket.org/{username}/{repo_slug}/admin/services?service=POST&url={your custom url}" you reference in this document stopped working today, our customers cannot use Bitbucket anymore this way. Can you please fix this?

    02 Aug 2013
    1. User avatar

      manthony

      Please file a ticket with support@bitbucket.org

       

      02 Aug 2013
  22. User avatar

    Anonymous

    I would suggest to create some API that returns the list of outgoing IP addresses (as it has been done by github).

    See http://developer.github.com/v3/meta/

    What do you think?

    03 Sep 2013
    1. User avatar

      Marcus Bertrand [Atlassian]

      Feature requests can be submitted over at https://bitbucket.org/site/master/issues/new. Please feel free to add that one!

      03 Sep 2013
  23. User avatar

    Anonymous

    Hi, would like to add some thing.!

    I was using POST hook for syncing bitbucket repository with my webserver.

    I found that, it was not working if i set commit temp file name (commit-4354676.53) without extension.

    I changed the gateway.php code on my server to create temp commit file with extension (".txt"), and 

    it started working.!!!

    I'm using Linux server, and i was using https://bitbucket.org/alixandru/bitbucket-sync/get/v1.0.0.zip

    this source for syncing, but it worked.

    Is there any way to get debug log/error log of all request made from bitbucket?

    07 Oct 2013
  24. User avatar

    Anonymous

    Is it possible to remove a hook using the API?

    30 Nov 2013
  25. User avatar

    Lorenzo Bugiani

    How can I determine for which branch belongs a commit? "branch" property is null for all commit, except for the last commit of all branches...

    01 Dec 2013
  26. User avatar

    Anonymous

    When pushing a new branch to the server, the commits array is empty. Makes it hard to tell what actually happened...

    14 Jan 2014
    1. User avatar

      Ignacio Freiberg

      The same thing happened to me when I push a branch that was just merged, but no new commits.

      30 Jan 2014
  27. User avatar

    Anonymous

    Is the POST hook expecting a response from the webservice we set up? I'm using this for continuous integration and I return 200 when successful, but sometimes processing can take a  while and I'm getting echoes.

    By any chance, do you have a routine that attempts to re-send the POST data in case you don't get a response ?

    24 Jan 2014
  28. User avatar

    Anonymous

    Hello! We are experiencing trouble with multiple POST hooks - the only one from the list (the last added, as I see) is used to send notification via POST request. Is it a correct behavior?

    21 Feb 2014
    1. User avatar

      Marcus Bertrand [Atlassian]

      All hooks should fire normally. If you aren't seeing this, please come to support with the details about your repository and the hooks you have setup.

      21 Feb 2014
  29. User avatar

    Jerome Guilbot

    I am getting echoes like one of the users above described, and you haven't answered his question.

    Do you guys expect a 200 response right after the hook is fired, if yes what is the timing?

    cc Marcus Bertrand [Atlassian]

    24 Mar 2014
    1. User avatar

      Marcus Bertrand [Atlassian]

      We wait for a response in the 200 -> 399 range of status codes. The timeout is set at 20 seconds. We'll get this added to this page soon.

      24 Mar 2014
  30. User avatar

    Thomas Beauvais

    I am having a hard time testing my application locally because I can't seem to find a cURL command that will mimac the Bitbucket web POST.

    curl --header "Content-Type: application/x-www-form-urlencoded" --request POST --form "payload=@doc/git/actual.json" http://localhost:9000/git

    Why is this a form with encoded data anyway?  Why not just "application/json" like a normal POST?

    07 Aug 2014
  31. User avatar

    Shea Martin

    Why does the hook send the payload as a Parameter instead of as the request body? This is a real PITA with .Net ApiControllers.

    06 Nov 2014
  32. User avatar

    Önder Ceylan

    It would be great to see a "new branch created" or "branch merge" data on payload. Serving an empty commits list is just not enough.

    14 Jan 2015
Powered by Confluence and Scroll Viewport