Unwanted webhook POST requests to connect app


One of our apps gets flooded with POST /webhook requests despite not having a webhooks module in the atlassian-connect.json.

This happens only on the production version and not on staging/development (where the app is installed via URL).

In the past, we had the webhooks module enabled for debug purposes, which could explain the calls for existing installations.

What is the best way to stop existing installations from executing the webhooks? A descriptor change did not help unfortunately.

Best regards,
Christian - Mibex Software

Hi Christian.ott,

that sounds weird - could you share your Connect app key (and maybe the types of webhooks you are receiving and the target workspaces) ? Also, feel free to open a support ticket if that’s easier to share sensitive data.

Hi @christian.ott,

I’ve done a bit of digging into your connect app. It looks like the lion-share (8504 out of 8611)
of installations still have a webhooks module in their descriptor. It looks like your original descriptors had the webhooks module defined, subscribing to all webhook events we publish. This explains why you have so much traffic coming to your webhooks endpoint.

From what I can see you’ve got 23 different “versions” of your descriptor floating around all with installations. Unfortunately when you push a new version of your descriptor, the existing installations of the older versions do not upgrade. New installations of your app will use whatever is the current “version” served by your descriptor url.

The good news is you should be able to update every old installation. We have an API which you (as the app vendor) are able to call for each installation, which allows you to upgrade installations to the latest served version of your app descriptor. Note that this endpoint only enables you to push changes which don’t require an increase in scopes.
To authenticate this request you craft a JWT token for the installation you wish to update. Unfortunately this means you’re required to make 1 call to update each installation.

Alternatively, we offer a different connect app model, called shared connect apps.

Shared Connect Apps vs Regular Connect Apps

This is not a well documented feature unfortunately (Getting started is the only place we talk about it), but It definitely is an improvement over the regular connect app model. For you it’d be useful for one of it’s key features; it allows you as app developers to push a new update of your app to all installations with the singular press of a button.

If you’re not increasing scopes, this change is instantaneous, and will update all installations in place.

If you have increased scopes the workspace admin for each workspace which has your app installed will receive an email stating that the app has been updated and the workspace admin has to consent the increase of scopes for the application.

Another advantage to the Shared connect application is that you have a singular secret shared all installations (hence the name) which saves having to store each installations unique secret.

The downside to this, is that once you’ve released a regular connect app out in the wild, it’s very hard to swap models to the Shared Connect App model. This is because the registration of the shared app requires that no installations using that key currently exist.

How to register a shared connect app

If you’re interested in using the shared app model, you’d probably need to register your app with a new app key which would mean producing a separate descriptor file.

  1. Go to your companies workspace and under workspace settings go to the Develop App page under the APPS AND FEATURES heading
  2. Add the public url you expose for your descriptor file
  3. Once you’ve added this you should get a nice listing and a nice installation URL.


You then use the installation URL to install the application in workspaces (your personal workspace, or even your organisation workspace). This registration process is a once-off task, and basically ties the app you’re developing to your workspace to allow you to perform the administrative tasks etc.

Please note, Registering a shared connect app doesn’t install the shared connect app. You still need to install it into your workspace if you wish to test it etc

The Manage Apps page stores the secret for your shared connect app so you can retrieve them to auth your requests back to Bitbucket from your server. The update button allows you to push updates to the current installations, it does this by re-retrieve the descriptor from the descriptor URL you setup when you registered the app. It first validates the descriptor and then updates the installations. The remove button will remove all installations and de-register the shared connect app.

Hope this helps,


Hi @DanFraser

Thanks a lot for the informative post! While we did know about the “Develop App” section, we have never heard explicitly of the difference between the shared connect app and the regular connect app.

We will register new apps to get the benefit of the shared secret :slight_smile:

What I’m not yet clear about is the transition of an existing regular connect app with a lot of users and available in the marketplace to a shared connect app. Is this possible without losing the installs?

Best regards,

1 Like

Hi @christian.ott,

The procedure to migrate between a regular connect app to a shared connect app is quite an involved and manual procedure. If you wish to go into this in more detail, it maybe easier to create a support ticket and we can work with you to migrate it.

It would require some work from your side, and some work from us, but it’s technically possible, so if you’re interested please feel free to reach out! The ability to easily push updates to existing installations is a massive improvement for vendors (and customers) in my opinion.

Best regards,

1 Like

Thanks for all the info on shared apps @DanFraser! I have another question: can shared apps be listed on the BBCloud Marketplace (which is manually maintained and somewhat disconnected from the original Atlassian Marketplace)? The goal is to make the shared app discoverable and installable for others via the MP, i.e. others would install via a click on the MP listing, not via a link that’s on our website.
If that is the case I would be very interested in migrating Workzone to be a shared app to push descriptor updates. Note that the app key com.izymes.workzone is used for server, dc and cloud as a single key.

Hi @izymesdev,

Yep, we’re able to list shared apps on the Bitbucket Marketplace, with no issues. As suggested above, I’d suggest raising a support ticket so it can be triaged with our engineering team.


1 Like

Hi @DanFraser

Thanks again for the information. We scripted the manual app update approach, and it’s working fine for us.

As a conversion to Forge may be on the (far) horizon, we will keep the apps as regular connect apps for now and re-evaluate the situation later again.

Best regards,

1 Like