JIRA WebHooks

What are WebHooks?

A webhook is a method of altering the behaviour of a web page or application with custom callbacks. It is a user-defined callback over HTTPS. You can use Jira webhooks to notify your app or web application when certain events occur in Jira.

Non Secure URLs won’t work as its deprecated, support for existing ones are still available. More details on Deprecation notice - Registering webhooks with non-secure URLs

Configuring a Webhook

In order to configure a Webhook on Jira, navigate to your Jira Settings > System > Webhooks

If you need to test out a Webhook, you can use this website https://webhook.site as its a Free Webhook listener, which shows you the response / event sent out by Jira.

  • Start by Clicking on the “Create Webhook” button.

  • Choose a name for the webhook created e.g. (“Webhook for Slack”)

  • the URL where the callback should be sent (only secure HTTPS URLs are allowed)

  • (optional) the scope of the webhook, for example either “all issues” or a limited set of issues specified by JQL ("project = ABC AND issuetype=Story")

  • the events to post to the URL, either “all events” or a specific set of events

Once the above is set, you can begin testing out your Webhooks. Please note that on Jira, Webhooks fires those events listed on the Webhook configuration page. Your API or custom script on the URL used should be listening for those Events fired by Jira which is in a JSON Payload format.

Example of a WebHook Payload

  • {{user_deleted}} Event

{
  "timestamp": 1555083153789,
  "webhookEvent": "user_deleted",
  "user": {
    "name": "removed1",
    "key": "557058:634a1e0e-3c8b-4a7b-88e6-a6faa5ccdc92",
    "accountId": "557058:634a1e0e-3c8b-4a7b-88e6-a6faa5ccdc92"
  }
}

webhook.png

All Available Events on Jira can be found here on WebHooks

Variable substitution in the webhook URL

You can append variables to the webhook URL when creating or updating a webhook. The variables are listed below:

  • ${board.id}

  • ${issue.id}

  • ${issue.key}

  • ${mergedVersion.id}

  • ${modifiedUser.accountId}

  • ${project.id}

  • ${project.key}

  • ${sprint.id}

  • ${version.id}

Example:

https://webhook.site/dexxxxb55-44fa-xxxx-xxxx-82cd66ca?${issue.key} Appending the ${issue.key} will dynamically insert the value of the current issue key. The same example goes for the above variable you want to substitute.

 

Caution

  • If the URL you have defined does not return a successful response to the webhook POST, Jira Cloud will retry sending three times.

  • Currently there is no backup or log available

Restrictions

We want to provide a performant experience for apps and their users. This is why the following limitations apply to this API:

  • Only webhooks for the jira:issue_created, jira:issue_updated, and jira:issue_deleted events are supported.

  • Webhooks are only permitted to use a subset of JQL:

    • Supported clauses: issueKey, project, issuetype, status, assignee, reporter, issue.property, cf[id] (for custom fields).

    • Only the epic label custom field is supported at the moment.

    • Supported operators: =, !=, IN, and NOT IN.

  • Only one callback URL is allowed, per Connect app per tenant.

  • Only a limited number of webhooks are permitted, per Connect app, per tenant. If you exceed the limit, an error will be returned by the REST API when you create new webhooks. This limit is subject to change and may increase in future.

Using REST API and WebHooks

Both REST API and Webhooks can be combined to achieve a better function of how you use Jira. If you want to use any method to send a request to Jira. Using REST API would be favourable as you can manipulate and control what happens on Jira programmatically. On the other hand, using Webhooks in conjunction with REST API provides an even greater control.

Therefore with the OAuth For REST API you can build a connect App that sends Incoming connections to Jira and then use the Webhooks to send out the Outgoing connections thus manipulating and control actions on Jira. Navigate to Jira Settings > Products > Application Links to begin the linking.

 

Adding webhooks to workflow post functions

Webhooks can be attached as a workflow post function. This makes it easy to trigger a webhook when an issue makes a workflow transition, for instance when it gets rejected from QA or when it gets resolved.

To add a webhook as a post function to a workflow:

  1. Configure your workflow and select the desired transition in the workflow designer. For more details, see Working with workflows.

  2. Click Post functions, then click Add post function.

  3. Select Trigger a Webhook from the list of post functions and click Add.

  4. Select the desired webhook from the list of webhooks and click Add to add the webhook as a post function.

Note:

  • If the webhook you choose is also configured to listen to events, then the webhook will be triggered twice: once for the event and once for the workflow transition. For this reason, you should always unselect all events from the webhook admin screen.

  • If a webhook is associated with a post-function, you will not be able to delete the webhook. You must disassociate it from the post-function first.

Issues associated with WebHooks not Working

  • Ensure that a Webhook was actually configured by Navigating to the Jira Settings > System > Webhooks

  • Check the Workflow, if the Webhook is not firing an Event for a Particular Status. Some issues resulted when the “Fire a Generic Event which will be processed by the Listener” was changed to a Custom created event or remove entirely from the Workflow.

  • Use https://webhook.site to ensure that Jira is actually sending out the payload

9 comments

Liam Green
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 4, 2021

Thanks for this - never fully understood what a WebHook was! 

Soumyadeep Mandal
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 4, 2021

Hi @Prince Nyeche ,

First of all, wish you a very happy new year!

Thanks for sharing this awesome article about webhooks. 

@Liam Green +1! 😋 🤣

Regards,

Soumyadeep (SaM)

Matt Doar
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
January 4, 2021

It's worth mentioning that if a JQL query is run for each event, the performance of Jira can suffer. We only use webhooks in transitions for this reason

https://confluence.atlassian.com/jirakb/webhook-configuration-best-practices-952060713.html

https://jira.atlassian.com/browse/JRASERVER-67421

Stuart Capel - London
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
January 4, 2021

Great article! I'm excited about using webhooks with Jira automation, I just need to find some time to experiment. Thanks for the detailed explanation though.

Taranjeet Singh
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
January 4, 2021

@Prince Nyeche Thanks for sharing this awesome and informative article about using Jira Webhooks. 

Prince Nyeche
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 4, 2021

@Soumyadeep Mandal Thanks, Happy New as well.

@Taranjeet Singh  Glad to share the knowledge as always.

Vinod Ramadoss
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 4, 2021

Thank you @Prince Nyeche , though I do not work directly making use of Jira webhooks I can definitely share the knowledge I gained reading this article as needed.

And, Thank you @Matt Doar , the links you shared has given more insights.

Yatish Madhav
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
March 25, 2024

Thanks for this @Prince Nyeche 

Is it just me or does testing Jira webhooks not work on https://webhook.site ?

Also, what does this mean "Only webhooks for the jira:issue_created, jira:issue_updated, and jira:issue_deleted events are supported." ? Does that mean that the rest of the events do not trigger webhook payloads?

I am trying to send webhook payloads to our custom connect app. Please help / advise how Jira can be authenticated with the app?

Please advise?

Prince Nyeche
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
March 26, 2024

Hey @Yatish Madhav 

The webhook.site does work with a simple connection, not sure how you've configured it though if it's not working for you. To your question, this article was more than 3 years ago. So the list of supported events has increased since then, you can find the updated list here.

For authentication using the webhooks API, only connect apps or OAuth authentication mechanisms can be used as mentioned in the docs. However, I believe the app itself had to have registered the webhook itself before it could be used to send or receive data. If you manually registered one from Jira UI, I'm not certain that would work.

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events