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

While attempting to register a webhook using an integration using 3LO Oauth instead of Connect, using the directions here:
https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-via-the-jira-rest-api--other-integrations-

I’ve POST’ed here:

https://api.atlassian.com/ex/jira/<id>/rest/webhooks/1.0/webhook

With a valid Oauth access token, which returns 403, “OAuth 2.0 is not enabled for this method.”

Without the token, it returns 401, “Client must be authenticated to access this resource.”
and

I also tried the same POST to:

https://<my-domain>.atlassian.net/rest/webhooks/1.0/webhook

Both with and without a token, it returns 401, “Client must be authenticated to access this resource.”

What’s the recommended way to register a webhook against the REST API when using Oauth?

Hi @JordanGlassman,

You are right about getting 401 and 403 while making request to https://api.atlassian.com/ex/jira/<id>/rest/webhooks/1.0/webhook. But I was able to register webhooks using https://<my-domain>.atlassian.net/rest/webhooks/1.0/webhook. I verified it in ‘Jira settings’ -> ‘Webhooks’ of my domain site and all looks good. Can you please share cURL command of request you are making?

Cheers,
Anmol

Hi @aagrawal2,

Here is the curl of an attempt to create a webhook using a valid Oauth access token, verified at another endpoint.

curl -X POST \
  https://jordan-test.atlassian.net/rest/webhooks/1.0/webhook \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Length: 245' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: atlassian.xsrf.token=de674509-30b9-4023-9431-9ebab99682b6_aaa7377dc2d31bca05d678bf7816f1b5c3ad6928_lout' \
  -H 'Host: jordan-test.atlassian.net' \
  -H 'Postman-Token: d766cca8-c1bd-4ff7-8c2d-1bd2538cfa63,a51711a2-d1b4-498c-95a8-1a1d13ad1b0e' \
  -H 'User-Agent: PostmanRuntime/7.15.2' \
  -H 'cache-control: no-cache' \
  -d ' {
  "name": "my first webhook via rest",
  "url": "https://www.example.com/webhooks",
  "events": [
    "jira:issue_created",
    "jira:issue_updated"
  ],
  "jqlFilter": "Project = JRA AND resolution = Fixed",
  "excludeIssueDetails" : false
}'

Result:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><status><status-code>401</status-code><message>Client must be authenticated to access this resource.</message></status>

I’m noticing that I can’t use Oauth with any of the https://jordan-test.atlassian.net/rest/ endpoints, which I see is documented here: https://developer.atlassian.com/cloud/jira/platform/oauth-2-authorization-code-grants-3lo-for-apps/#3-2-construct-the-request-url.

You are right about getting 401 and 403 while making request to https://api.atlassian.com/ex/jira/<id>/rest/webhooks/1.0/webhook .

Does that mean it isn’t possible to create webhooks using Oauth?

Thank you,
-Jordan

I’m also seeing conflicting statements in the documentation about this too:

This indicates that registering dynamic webhooks with other integrations (which I interpret to be 3LO Oauth2) is possible:
https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-via-the-jira-rest-api--other-integrations-

Whereas this says only connect apps can do it:
https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-webhook-post

Hi @JordanGlassman,

I discussed with my team on this and your confusion is understandable. Let me try clarifying those:

  • As mentioned in 3LO docs, “Requests that use OAuth 2.0 (3LO) are made via api.atlassian.com (not https://your-domain.atlassian.net )”, you will have to use api.atlassian.com for your need. https://your-domain.atlassian.net is to make call from your Connect app or from some kind fo script (like cronjob).
  • Webhook registration service is currently available only in Connect app and not yet in 3LO. It’s still a work in progress.
  • In your curl request, you are calling the Connect app’s REST API with access token, which is why it is not working. For it to work, you will have to use basic auth, i.e. email and API token.

Hope this helps you. Let me know if you have any more questions.

Cheers,
Anmol

Hey Anmol,

Do you know how close the REST 3LO webhook APIs are? As a rough guess are we talking weeks or months?

Cheers,
James

Hi James,

It’s not coming up this quarter. That’s all I have so far.

Cheer,
Anmol

This is a big blocker for us too, does this mean we’ll have to query for issue creates/updates & comments periodically or is there a beta version of hooks via the rest api for non-connect apps we can use until the stable release ships?

3 Likes

Please update latest status

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.

2 Likes

@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