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

#22

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
#23

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 ( https://ecosystem.atlassian.net/browse/ACJIRA-2173 ). 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 https://atlaskit.atlassian.com/packages/editor/adf-utils and https://atlaskit.atlassian.com/packages/editor/adf-schema 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 https://unifiedjs.com/explore/package/remark-mdx/ 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!