Managing Webhooks
Webhooks are user-defined HTTP POST callbacks. They provide a lightweight mechanism for letting remote applications receive push notifications from JIRA, without requiring polling. For example, you may want any changes in JIRA bugs to be pushed to a test management system, so that they can be retested.
JIRA supports webhooks for all standard issue-related events (i.e. not custom events), e.g. issue_created, issue_assigned, etc. Issue events are pushed to a specified URL in JSON format. You can constrain the scope of the webhook by specifying the desired issue events and/or JQL.
Please read the JIRA Webhooks Overview page which contains detailed information on JIRA webhooks. This page only contains instructions on how to use the Webhooks user interface in the JIRA administration console.
On this page:
Viewing webhooks in JIRA
To view webhooks in JIRA,
- Log in as a user with the JIRA Administrators global permission.
- Choose
> System. Select Advanced > Webhooks to open the Webhooks page, which shows a list of all existing webhooks.
Keyboard shortcut: g + g + start typing webhooks - Click the summary of the webhook in the left 'Webhooks' column to display the details of the webhook.
Screenshot: Webhooks displayed in the JIRA administration console
Managing webhooks via the JIRA administration console
Webhooks can be registered (created), edited and deleted via the JIRA administration console, REST calls or the installation of a "Remote App". The instructions on this page describe how to manage webhooks via the JIRA administration console. Please see the JIRA Webhooks Overview page for information on the other methods.
To manage webhooks in JIRA,
- Log in as a user with the JIRA Administrators global permission.
- Choose > System. Select Advanced > Webhooks to open the Webhooks page, which shows a list of all existing webhooks. Keyboard shortcut: g + g + start typing webhooks
- Create/register, edit or delete webhooks as desired.
- Create — Click Add a Webhook, enter the webhook details and click Create.
- Edit — Select the desired webhook in the summary list on the left, click Edit, update the webhook details and click Save.
- Delete — Select the desired webhook in the summary list on the left, and click Delete in the webhook details.
- Disable — Select the desired webhook in the summary list on the left, and click Disable in the webhook details. Disabling a webhook prevents the webhook from firing.
- Enable (disabled webhooks only) — Select the desired disabled webhook in the summary list on the left, and click Enable in the webhook details.
Tips for managing a webhook
- Constraining the webhook to a set of issues/issue events — By default, a webhook will fire for all events of all issues in a JIRA installation. You can constrain this to a set of issues and a set of issue events (or no issue events). To do this, specify the desired set of issues (via a JQL statement) and the set of issue events, when you create or edit a webhook. For example, the webhook in the screenshot above will only fire when bugs with an affected version of "1.0" are updated.
- Omitting the JSON from the POST — If you are integrating with a system where only a POST URL is required to trigger the action, and having a body with data breaks the integration, you can configure the webhook so that it does not send the JSON with the POST. To do this, select the Exclude details checkbox when editing your webhook.
- Determining the changes in an 'Issue Updated' event — A changelog is sent with the 'Issue Updated' event (excepting the
issue_generic_event). You can listen for this event and check the changelog for the changes.
Extending your webhook
Trigger your webhook from a workflow post function
Please note, if a webhook is associated with a post-function, you cannot be delete the webhook. You must disassociate it from the post-function first.
Add an issue key variable to your webhook
You can add an issue key variable to your webhook by inserting ${issue.key} in your webhook URL. When the webhook fires for an issue, the issue key will be substituted for the variable in the URL.
For example, say you have the following web hook URL with the ${issue.key} variable:
http://example.com/bamboo/rest/api/latest/queue/BAMBOO/${issue.key}If the web hook is fired for a JIRA issue with the key JRA-1234, the URL that the web hooked is posted to will be:
http://example.com/bamboo/rest/api/latest/queue/BAMBOO/JRA-1234
Known issues
- Post function web hooks will not fire if added to the Create Issue workflow transition. We recommend that you configure your web hook to fire from the issue_created event instead.
- If you are using webhooks in JIRA Cloud, there is a known issue that restricts the port numbers that can be specified in the webhook URL. If you do not follow the guidelines below, then the webhook will not trigger.
- If you are using HTTP and specify a port number in the webhook URL, the port number must be 80. Note, if you do not specify a port number, the webhook will work.
- If you are using HTTPS and specify a port number in the webhook URL, the port number must be 443. Note, if you do not specify a port number, the webhook will work.