Skip to end of metadata
Go to start of metadata

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


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. 



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


  1. 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?

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

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

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

  4. 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 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.



    1. Musti, please send an email to with your questions. 

  5. 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?


  6. 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?

    1. 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.

      1. 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.

  7. 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.

    1. 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.

      1. Ah, that will do nicely, thank you.

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

    1. 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.


  9. Anonymous

    Which variable exactly houses the POST data in PHP?

    1. Anonymous

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

      1. Anonymous


  10. 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"?

  11. Anonymous

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

    1. The possible types are modified, added and removed.  

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

    1. 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.

  13. 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

    1. 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.

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

        Correct me if I am wrong.

  14. The IP address change was announced via our blog:

    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. 

  15. 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.

  16. 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?

  17. Anonymous

    As per, outgoing IP addresses need to be updated to and

    1. Thanks for the catch. Updated.

  18. Anonymous

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

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

  19. 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.

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

      1. I confirm, payload requires a parsing

        1. Documentation is still incorrect, payload is still an escaped string

  20. Anonymous

    The link "{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?

    1. Please file a ticket with


  21. Anonymous

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


    What do you think?

    1. Feature requests can be submitted over at Please feel free to add that one!

  22. 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

    this source for syncing, but it worked.

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

  23. Anonymous

    Is it possible to remove a hook using the API?

  24. 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...

  25. Anonymous

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

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

  26. 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 ?

  27. 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?

    1. 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.

  28. 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]

    1. 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.

  29. 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?

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

  31. 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.