Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal

Recognition

  • Give kudos
  • Received
  • Given

Leaderboard

  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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

7 comments

Liam Green Community Leader Jan 04, 2021

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

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)

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 C Community Leader Jan 04, 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 Jan 04, 2021

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

Prince Nyeche Community Leader Jan 04, 2021

@Soumyadeep Mandal Thanks, Happy New as well.

@Taranjeet Singh  Glad to share the knowledge as always.

Vinod Ramadoss Community Leader Jan 04, 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__ LinkedIn , the links you shared has given more insights.

Comment

Log in or Sign up to comment
TAGS

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you