How can I register a webhook using the REST API when using 3LO OAuth2?

Hi,
Could you help me with this issue? I’m having trouble registering webhooks via an app connect.

Best regards.

Hey folks, wanted to give a quick update here.

Unfortunately it’s still the case that webhooks are not supported in 3LO apps. To use webhooks in 3LO apps, you’ll need to build an app via the Connect framework. There’s a feature request being tracked for webhooks in 3LO here.

As a workaround, if you need to use OAuth 2.0 authentication for your app, and you require the ability to respond to/listen for product events in the immediate term, consider trying out the Forge platform (currently in beta). The Forge platform is backed by OAuth 2.0 authentication and has “product events” which you can consider webhook equivalents. Access requires an invitation at this time, but if you apply for the waitlist and let me know I can accelerate your acceptance. You can view the list of product events supported through Forge here.

2 Likes

Cheers for the update Simon :slight_smile:

Really looking forward to this one dropping so we can get rid of basic auth in our app!


James Sear
Co-founder, Avion

Thanks for sharing this, Simon. I’ve just signed up on the waitlist. Would you be able to accelerate the application?

@SimonKubica, I’ve just joined the waitlist, could you please accelerate the access for me? Thank you

@SimonKubica Connect, or Forge are not the solution here, and not even a workaround, because it requires Jira administrators to install such apps on the instance, and this defeats the purpose of 3LO apps.
The idea of 3LO app is that an user can just start using them, and Jira admin is no longer a bottleneck.

I suggest to have a look at GitHub OAuth apps ecosystem, it’s much more straight forward (and therefore successful, many great apps out there!).

The workaround for the webhooks problem which one can use as a 3LO app is polling, but this is suboptimal for all parties: user, Atlassian, and the app vendor.

@SimonKubica can you explain to other developers how a tool like Zapier is able to trigger on updates using a standard OAuth 2.0 connection? I can’t believe that polling is the preferred way to do this… and as @Grzegorz.Tanczyk implied, a Connect or Forge app is a non-starter here because an admin has to install it (and is not how Zapier or other intergration-as-as-service platforms are doing it).

Please share the roadmap for Official launch officially OL3
TY

The current state of OAuth2 and Jira REST API is not helpful.

Your documentation states: " Building a non-Connect integration ? If you are building an integration that doesn’t use Connect, we recommend that you use OAuth 2.0 authorization code grants (3LO) for apps over other authentication methods, such as basic authentication and OAuth 1.0a. See Security for other integrations."

However, two of the most important APIs to be able to build an effective integration with Jira, this one (creating webhooks) and Createmeta are not yet implemented. So it’s impossible to know which fields are required to create an issue, and impossible to create a webhook to creative integrations that are useful.

Until issues like this are fixed you should frankly have a big warning with the suggestion with all of the APIs that do not currently work with OAuth2 and the REST API.

What is your recommended advice? Switch to Oauth 1.0a?

1 Like

Hey @DylanSchiemann and @Grzegorz.Tanczyk,

Yeah, I totally agree that for a large percentage of use cases, you’re blocked if you don’t have access to webhooks. I’ll circle with the team to ensure we’ve updated our documentation to flag this limitation of OAuth 2.0 integrations up-front.

I definitely sympathize with the tricky situation of not being able to use Connect (because you want user-based auth), and not being able to use an OAuth 2.0 integration (because you want webhooks). We don’t have a great answer for that right now outside of polling, and I’ll make sure to keep that top-of-mind as we plan out our roadmap and upcoming features and functionality for the platform.

It’s my understanding that only Connect apps can listen for webhooks, which would rule out OAuth 1.0a as well. Although I’ve followed that up with the team and will edit this post if it turns out my understanding is incorrect.

The best advice I can offer at this point in time is to use the platform with webhooks functionality (Connect). If this isn’t possible because of the admin installation requirement, what would be really helpful for me in advocating for roadmap time on this is a clear outline of your app’s use case, and why it’s infeasible to have an admin install it.

1 Like

Thanks @SimonKubica,

I think the primary reason to use the REST APIs over Connect or Forge is when you’re building an app that integrates with Jira but is not intended to live within the Jira app UI itself. Connect seems to have a higher overhead and set of requirements by comparison, but perhaps it is just not explained clearly in the overview documentation or I’m misunderstanding?

Regarding Webhooks, I’ve tried OAuth 2.0, OAuth 1.0a, and Basic Auth. Of the 3 basic auth seems to get the closest, but the body content I send over does not seem to get read by the API call and I get an error back that name and url need to be provided even though they are.

There are a few other areas where OAuth 2.0 is incomplete where falling back to OAuth 1.0a or Basic Auth “works”, but either requires a less secure integration or for users to authenticate in multiple ways. For example, the ability to get the metadata to create an issue is not supported with OAuth 2.0.

While I have not looked through every API, it feels like things are so close to just working with OAuth 2.0, but these obstacles likely cost everyone trying to do an integration with OAuth 2.0 a lot of pain and wasted time. Definitely updating the docs is a good start, but fixing them would lead to integrations that are more secure and efficient. Thanks!

Regards,
-Dylan

I think the primary reason to use the REST APIs over Connect or Forge is when you’re building an app that integrates with Jira but is not intended to live within the Jira app UI itself. Connect seems to have a higher overhead and set of requirements by comparison, but perhaps it is just not explained clearly in the overview documentation or I’m misunderstanding?

At the moment, Forge and Connect definitely aren’t in the “just copy your secret at go” state, so I agree with you in terms of where things are at today – it isn’t great that you need to choose between a simple starting experience and a whole host of useful functionality (like webhooks) when you’re building an integration.

This is something that we definitely want to make better. How we’re looking at things right now, I think it’s more likely we’ll achieve this through evolving Forge/OAuth 2.0 so that they become the go-to for all use cases, and making it as simple as possible to get started regardless of what you’re building. This will allow us to get to a better experience faster than trying to add equivalent functionality to each of basic auth, OAuth 1.0a apps, OAuth 2.0 apps, Connect, Forge. The sooner we consolidate, the less likelihood developers will have to “paradigm shift” to an entirely new platform/framework when they need a particular piece of functionality (again, like webhooks).

Of the 3 basic auth seems to get the closest, but the body content I send over does not seem to get read by the API call and I get an error back that name and url need to be provided even though they are.

I’ve heard back from the team and confirmed that listening for webhooks is a feature of Connect only. If you’re experiencing what looks like a bug with basic though, feel free to shoot me over the fine-grained details of that and I’ll go ahead and create a bug for you.

There are a few other areas where OAuth 2.0 is incomplete where falling back to OAuth 1.0a or Basic Auth “works”

If possible, would you be able to reply here/shoot me a DM enumerating each of these? It would be incredibly helpful for the team, for the reason I’m about to explain next.

While I have not looked through every API, it feels like things are so close to just working with OAuth 2.0, but these obstacles likely cost everyone trying to do an integration with OAuth 2.0 a lot of pain and wasted time.

Mate, couldn’t agree more. It’s certainly what we’re working towards, with progress made already and plenty more to come (i.e. I know we’re quite close to having full parity in terms of the APIs you can call via OAuth 2). I really appreciate the time you and everyone else is taking to outline exactly what’s missing and what’s important, it’s definitely helping us get there faster :slight_smile:

3 Likes

Hi @SimonKubica,

Thanks for the thoughtful feedback. I am VERY new to working with the Jira APIs (e.g. 2-3 weeks in).

I think the strategy of focusing on Forge and OAuth 2.0 makes a lot of sense, there are definitely too many choices currently (which is a bad thing only because they don’t have parity).

My note about webhooks and basic auth was somewhat of a surprise while trying all the things. When trying webhooks with OAuth 2, I get a pretty clear error that things are not authorized or allowed. When I tried basic auth, it seemed that authorization happened, but the data from my request wasn’t copied, so I received a warning that I had failed to provide a name and url. So I was wondering if maybe the creation of webhooks was supposed to work with basic auth and the REST APIs, but that either the documentation on what data to provide and in what format was incorrect, or if I was wasting my time trying to get something to work. :slight_smile:

The other area I found where OAuth 2 does not work is with the previously mentioned query for which fields are required to create an issue ( [ACJIRA-2173] - Ecosystem Jira ). It’s possible there are others but I’ve not encountered them yet.

A couple of areas where I did struggle at first:

  • Refresh tokens. It wasn’t obvious front and center that OAuth 2 tokens are valid for an hour. Perhaps make that far more obvious in the early parts of the docs. Also it seems like you can refresh an expired token for “a while”, but if you want too long then you need to restart the auth process.
  • For createmeta, the provided examples in the API documentation fail to show a request to get expanded information which is necessary to determine which fields are required. Because every Jira project has the potential for different custom fields, even just getting a simple list of required fields by issuetype would be beneficial.
  • Working with ADF is a challenge currently. There is Atlaskit by Atlassian and Atlaskit by Atlassian but to say the documentation there is light would be an understatement, lol. In an idea world there would be APIs to convert to and from other common formats like markdown and HTML. Even better, UnifiedJS ( https://unifiedjs.com/ ) and remark have a nice ecosystem of tools to convert from one abstract syntax tree to another, so having something like remark-mdx - unified but for ADF would be super beneficial.
  • Some of the APIs send back a lot of data that may not be necessary. Obviously the preference is to be able to get everything you need, but there are definitely places where it feels like a filter on which fields get returned would be nice (for example, on the createmeta query, what I really want the most terse response possible to tell me exactly what I need to provide to create a new issue).

Hopefully this helps and makes sense!

1 Like

Hi @SimonKubica,

A quick update on this. The createmeta challenges from before seem to have been fixed, so that progress is nice to see.

Do you have any updates to provide on OAuth2 support for managing webhooks? Currently this leaves Jira lagging significantly behind the OAuth APIs for other platforms (Linear, Asana, GitHub issues, Pivotal Tracker, Basecamp, etc.).

Thanks,
-Dylan

1 Like

@DylanSchiemann I have been following this ticket for a while, and it recently moved into “In Progress”, so hopefully this is moving!

https://ecosystem.atlassian.net/browse/ACJIRA-1632

Just to follow up on the original post in this thread, 3LO is now available for the newer webhook endpoint:

1 Like

2 posts were split to a new topic: Question about OAuth 2.0 (3LO) Webhooks

A post was split to a new topic: Register a webhook using REST API and OAuth 1.0a

Is there any update now? Solved or not?

@CharlesHusman,

Thanks for prompting again for clarification. I realize the documentation can be confusing but it isn’t wrong.

To explain, there are multiple versions of the webhook endpoint. The REST API v3 docs, correctly indicate only 3LO and Connect can register webhooks via POST /rest/api/3/webhook.

Meanwhile, the “Other integrations” documentation is documentation for the otherwise undocumented POST /rest/webhooks/1.0/webhook, where basic auth (via API tokens) still works. (Until today, I assumed also OAuth 1.0a.) This endpoint does not work with 3LO.

When you find documentation problems and ambiguities, please be sure to use the page rating feature to send feedback.
image