The new Bitbucket webhooks

By on June 24, 2015

Bitbucket webhooks are used by teams every day to test, analyze, deploy, and distribute great software to millions of people.

As Bitbucket webhooks are one of our most popular integration points, we’ve had the opportunity to gather lots of feedback regarding our webhook payloads, usage, and integrations.

We’ve listened to the community (check out public issues #7775, #5938, #4467, #6545 + more) and collaborated with CI vendors to make crucial improvements to this process.

We’re proud to announce the new Bitbucket webhooks.

webhooks

The new webhooks can be accessed in your repository administration settings as shown in the image above. The webhooks provide a host of improvements over the previous, and soon-to-be deprecated “POST and Pull Request POST” hooks, which have now been renamed to “Services”.

Let’s look at some of the improvements and attributes of the new webhooks.

Fuller, more descriptive payload

Bitbucket webhooks now send more comprehensive information in the payload. For example, a repo:push event now includes detailed payload information about each and every reference that was updated:

payloads

Please visit our payload documentation for more examples of changes and improvements.

Better controls

We’ve added fine-grained control over the events you want to receive hooks for, such as repository, issue, and pull request events:

triggers

Improved troubleshooting

You can now troubleshoot malfunctioning webhooks more easily by reviewing the recent requests, including status codes and response times:

requests

Connect-ed

The new Bitbucket webhooks have been written from the ground up as a Connect add-on using our Atlassian Connect for Bitbucket platform, leveraging the same APIs for building powerful add-ons for extending Bitbucket.

Onward!

This is just the beginning. We’ve got more features on the way, such as viewing request details (headers, event payloads, etc.), retrying requests, advanced queuing, and much more.

If you’re currently integrating with the old webhooks (renamed to “Services”), these will be deprecated soon. Please visit our payload documentation for the new payload descriptions.

Take the new Bitbucket webhooks for a spin – you can configure them in your repository settings. Are you inspired to build new, exciting integrations?  Clone our webhook-listener demo project to quickly get started with Bitbucket webhooks.

18 Comments

  • tOMPSON
    Posted June 24, 2015 at 8:05 am | Permalink

    Great, thank you, we waited so long for this and now it works very well!

    One thing: next time please improve communication in bug reports – there were months (if not years) of silence from your side which left customers wondering if you even read those reports.

    • Dennis Kromhout van der Meer
      Posted June 25, 2015 at 9:25 am | Permalink

      Thank you for your feedback! We’re trying to do a better job on communicating our efforts to the community, but we have to be careful not to over-promise and under-deliver, which caused problems in the past. However, I can guarantee you that all of the top issues are on our radar; expect more frequent updates in the future.

  • Chris Atomix
    Posted June 24, 2015 at 5:44 pm | Permalink

    It says the old webhooks (“Services”) will be “deprecated soon”. When is soon? How much time do I have to rewrite my Bitbucket integrations to use the new webhooks?

    • Dennis Kromhout van der Meer
      Posted June 25, 2015 at 9:16 am | Permalink

      We’d like to give all our integrators enough time to switch over. I expect full deprecation in 6 months from now. Let me know if you need help to switch over.

      • Chris Atomix
        Posted June 25, 2015 at 5:19 pm | Permalink

        6 months is more than adequate for us, thanks!

        • Suwat Ch
          Posted July 18, 2015 at 10:03 pm | Permalink

          Hi, I am working with Microsoft Azure. We have scenarios where we integrate with Bitbucket. Question about deprecation.
          1. existing REST api to set hook will be deprecated (failed) or it adds hook url to the new webhook instead.
          2. the already setup services url will be depreated (stop receiving notification) or it will receive the new format instead.

          It will be simpler for our migration to have existing hook/api to just work with new format.

  • Marcus
    Posted August 5, 2015 at 4:42 am | Permalink

    Is the new Push webhook backwards compatible with the old POST webook?

  • Dan Crack
    Posted August 5, 2015 at 3:08 pm | Permalink

    Is there any plan to extend the Controls/Triggers to have branch specific detail? e.g Trigger>Repository>Pushed to Branch:’Develop’
    ?

    • Herrmann Hinz
      Posted January 12, 2016 at 2:59 pm | Permalink

      that would be come in quite handy. yes. please let me know also.

    • Stephan
      Posted March 11, 2016 at 2:55 pm | Permalink

      +1 would really be helpful

  • bobo
    Posted August 6, 2015 at 2:43 am | Permalink

    Hope you can notify users that your `Something` has changed by email or something, many thirdparty apps may have been affected and they may no longer work

  • Pedro Esperanca
    Posted September 6, 2015 at 7:41 am | Permalink

    I had an account on twitter that anounced everytime a tweet was made, it stopped working.. probably because of this..
    Any idea how I can get it back to work ?

  • Xin Chen
    Posted November 4, 2015 at 8:07 am | Permalink

    How does BitBucket webhook pass a parameter (such as the PR number) via the trigger?
    for example, I would like to create a webhook to trigger a jenkins job but I would like the Jenkins job to know from which PR this trigger was coming from.

    • Hanno Opperman
      Posted April 4, 2016 at 2:58 am | Permalink

      Hi, did you manage to figure this out? 🙂

  • Posted December 29, 2015 at 8:25 am | Permalink

    Is this available to Stash / Bitbucket server users?

  • Posted April 2, 2016 at 12:51 pm | Permalink

    It’s been almost a year at this point. Are there any plans to extend this to Bitbucket Server? It seems really strange that the _enterprise_ product doesn’t have this ability, since it’s _so_ important to build custom integrations.

    • peter
      Posted May 31, 2016 at 10:22 am | Permalink

      Exactly my thoughts. Stash seems to lag behind the cloud version all the time despite the fact that a lot of $M enterprises prefer it.

      In our case the branch information would be essential to create effective build pipelines. Third-party plugins can’t deliver either…

      • mindsocket
        Posted June 1, 2016 at 4:29 am | Permalink

        Thanks for the feedback. Better webhooks are something we’d like to add to Bitbucket Server, but due to other priorities we don’t currently have a clear timeline for when it will be delivered.