Configuring webhook security
Webhook secret tokens
A secret token is a random string known only to Jira and your source code repository hosting provider. This adds an extra layer of authentication by ensuring that Jira accepts webhook requests only from trusted source code repositories — that is, repositories that can authenticate webhook requests in one of the following ways:
- by sending the secret token in the webhook request header (like GitLab)
- by sending a signature generated based on the webhook secret token (like GitHub and Bitbucket)
Jira automatically generates and sets webhook secret tokens for all of your linked DVCS accounts. Every linked DVCS account is secured by a unique token. No manual configuration is required.
Linking a new DVCS account will result in Jira generating a unique webhook secret token and saving it to all the repositories that belong to the account.
Adding another repository to an already linked account will prompt Jira to save that account's token to the new repository.
Setting webhook secret tokens for the first time
Starting with Jira 9.4.11, in order for Jira to be able to accept webhook requests from your source code repositories, DVCS webhooks must be secured with secret tokens. After upgrading to 9.4.11, Jira will start securing all your existing DVCS accounts with webhook secret tokens.
You may experience a delay in the synchronization of repository data. The time to completion will depend on the number of repositories to process.
While the first-time generation and configuration of webhook secret tokens is in progress, you'll see the Webhook security statistics panel appear on on the DVCS accounts page. The panel displays the total number of repositories in your accounts and shows the progress of the operation. The panel disappears once all your DVCS accounts have been secured.
Status indicators
Jira reflects the status of operations such as setting webhook secret tokens for the first time or changing an account's token using the following indicators. The indicators appear on the DVCS accounts page (where they mark the security status of the DVCS account as a whole) and on the DVCS account details page (marking the security status of individual repositories in that account).
The following table describes the possible status indicators:
| Status | Description |
|---|---|
PENDING | An account or repository marked with this indicator is not yet secured with a webhook secret token and awaits the configuration to begin. |
SECURE | The communication between Jira and the source code repositories that belong to the account marked by this indicator is secured with a unique webhook secret token. |
CONFIGURING | A webhook secret token has been successfully generated for the account marked with this indicator, and Jira is now saving the new token to all the repositories that belong to that account. The time to completion will depend on the number of repositories to process. |
FAILED | A webhook secret token has been successfully generated for the account marked by this indicator, but Jira couldn’t set the new token in all the source code repositories that belong to that account. |
Previewing the webhook secret token
To preview the webhook secret token generated for an account:
- In the upper-right corner of the screen, select Administration
> Applications. Under Integrations, select DVCS Accounts.
Next to an existing DVCS account, select More options ••• > Webhook security.
- In the Webhook security dialog, under Secret token, select the Show token
button. - Optionally, to hide the webhook secret token again, select the Hide token
button or close the Webhook security dialog.
Copying the webhook secret token to the clipboard
To copy the secret token generated for an account to your clipboard:
- In the upper-right corner of the screen, select Administration > Applications.
Under Integrations, select DVCS Accounts.
Next to an existing DVCS account, select More options ••• > Webhook security.
- In the Webhook security dialog, under Secret token, select the Copy to clipboard
button.
Changing the webhook secret token for an account
When you change the secret token, Jira will generate a new one and set it in all the source code repositories in the account where you've requested the change.
Changing the webhook secret token can’t be undone, but you can restart the operation at any time.
You may experience a delay in the synchronization of repository data. The time to completion will depend on the number of repositories to process.
To change the webhook secret token for an account:
- In the upper-right corner of the screen, select Administration > Applications.
Under Integrations, select DVCS Accounts.
Next to an existing DVCS account, select More options ••• > Webhook security.
- In the Webhook security dialog, select Change secret token.