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"
}
}
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:
Configure your workflow and select the desired transition in the workflow designer. For more details, see Working with workflows.
Click Post functions, then click Add post function.
Select Trigger a Webhook from the list of post functions and click Add.
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
Was this helpful?
Thanks!
Prince Nyeche
9 comments