Webhooks

Created by Shanmarc Florete
Last updated: Mar 30, 2021

What’s on this page:

What are webhooks and why use them?

Webhooks can be an extremely powerful tool that can be configured to trigger an immediate re-index of your repositories from remote systems. Your git server can send this near real-time data to Jira when your git data changes. This results in much faster indexing time so that you don’t have to wait for the regular polling interval (see General settings).

Webhooks can be triggered whenever certain actions are performed. For example, you can configure a webhook to execute when:

  • new commit is pushed

  • pull request is opened

  • branch is merged

You can create webhooks for individual repositories or most git providers will allow you to create webhooks at an account-level or org-level.

Do I need to set up webhooks?

Short answer is no, the regular reindexing configured in General settings by the Jira administrator is the base requirement for indexing. However, by configuring webhooks to trigger reindexing, Jira will more often have up-to-date information. The normal frequency of the app limits this by polling at set intervals.

Without webhooks, you will rely on the default polling of the app which is unchangeable by non-Jira administrators. Jira users will have to wait for the default interval for updates which means users will not see new commits or pull requests until the next indexing interval.

Getting started

Important
To use the webhooks feature, it must be enabled in the Manage (Git) repositories page.

Configure webhooks to trigger immediate reindex of your repositories from remote systems.

  1. From your Jira dashboard, go to menu Git ➜ Manage repositories. On the sidebar, under Git Integration for Jira, click Webhooks.

  2. Enable/disable the webhook feature by clicking on the Enabled/Disabled option.

Copy the webhook URL to the system clipboard by clicking the copy icon adjacent to the right.  Use this URL when required by the repository web hooks setting of your git host.

The Secret Key is a secure random-generated alphanumeric string at the time of the Git Integration for Jira app installation.  The user can change this to a different value by generating another secret token according to your Git host.

Use this key in the form of:

1 <JIRA_BASE_URL>/git/webhook/reindex/<SECRET_KEY>

Assign your Jira base URL and Secret Key to the sample URL structure

Assign your Jira base URL and Secret Key to the sample URL structure

Example:

1 https://your.jira.com/rest/gitplugin/webhook/1.0/reindex/sdf34tGdfgGDG345g3y0045TYG23te37

All the repositories will be reindexed if the URL specified above is activated through GET, POST, or PUT and the webhooks are enabled.

There is no support for other HTTP methods such as DELETE or HEAD.

GitHub/GitLab push events

The Git Integration for Jira app supports GitLab and GitHub push event to define individual repository to index.

The webhook parses the following payload formats:

GITHUB (Introduced v2.7.10)

GITHUB (Introduced v2.7.10)

1 2 3 4 5 6 7 8 { "repository": { "git_url": "git://github.com/testuser01/test-repo.git", "ssh_url": "git@github.com:testuser01/test-repo.git", "clone_url": "https://github.com/testuser01/public-repo.git", "svn_url": "https://github.com/testuser01/public-repo" } }

GITLAB

GITLAB

1 2 3 4 5 6 { "repository": { "git_ssh_url": "git@gitlab.com:testuser01/test-master.git", "git_http_url": "https://gitlab.com/testuser01/test-master.git" } }