Guide to configure a webhook in SonarQube
Webhooks are configured for sending notification to a web address that an event has occurred. In SonarQube, webhooks are configured to send notification to third party services to notify them of the SonarQube code analysis completion. In this post we will discuss in detail why to configure a webhook and how to configure a webhook in SonarQube with Jenkins as the third party CI tool. We will go through few issues that one might face while setting up webhooks as well as guidance for their resolution.
Below is the sequence in which we will proceed. Feel free to jump to any sub topic of your interest.
- Section 1-
- Section3 –
- Section4 –
- Section 5 –
- Section 6 –
What is a Webhook in SonarQube
Webhooks are triggered when an event occurs. They then send a message or a payload to the URL that is configured for the webhook. In SonarQube, webhooks are triggered when SonarQube code analysis is completed and an external service needs to be notified. A JSON payload is sent to the configured URL as a http POST request.
Learn more about SonarQube:
👉 To read other posts regarding SonarQube Click here
Why do we need a Webhook in SonarQube
Now let us consider the scenario to understand why webhooks are required to be configured in SonarQube.
We will understand this scenario with Jenkins as the CI tool. When we integrate Sonarube with a CI tool like Jenkins, we trigger the code analysis in SonarQube from Jenkins. Once the analysis is completed, we expect that the result from SonarQube analysis will be available in Jenkins. These tasks work sequentially. That means as soon as the SonarQube analysis is completed, it has to send back the result to Jenkins. If the result is ready in SonarQube just after the analysis is completed, the result will be available to Jenkins.
But at times, there is a time gap between completion of sonar analysis and the generation of analysis report by SonarQube based on which it can be decided, whether the project has passed the analysis (Quality Gate) or not. In this case, the task will remain in IN-PROGRESS status in Jenkins till the timeout happens.
Hence we need to create a webhook in SonarQube which enables SonarQube to notify to Jenkins that the task is completed and the analysis report is available. Jenkins will then be able to provide the result of the Quality Gate as Passed or Failed as soon as it is notified via a webhook.
How to configure a Webhook in SonarQube
You can configure a webhook at a Global level or a Project level. Here we will create a webhook at global level. For this we will go to Administration > Configurations > Webhooks as shown in the image below.
If you want to create a webhook at project level, go to Projects tab, then click on the name of your project, and then Project Settings > Webhooks.
Below is the webhook screen. It shows a list of configured webhooks.
We will now click on the Create button on the right side of this screen.
This will open a new window, where we need to provide the details for the webhook.
Provide the Name of the webhook. URL should be your URL for Jenkins followed by /sonarqube-webhook. Save the webhook and we are all set.
Now go to Jenkins and run the Sonar analysis again from your Jenkins pipeline (covered in the next section). If your webhook is setup properly, it will return the status of the analysis in the Quality Gate stage.
How to use SonarQube Webhook with Jenkins Pipeline
We will run SonarQube analysis from Jenkins pipeline project. Here we will have 2 stages i.e.
i. Static Analysis, this will be the project analysis by SonarQube
ii. Quality Gate, in this stage we will show whether the analysis has passed or failed. This result will be based on the analysis report created in SonarQube. The webhook will show the result in Jenkins when it is ready.
To view Jenkins pipeline code for SonarQube refer to this post: SonarQube integration with Jenkins Pipeline
Note: You might also be able to see the result in Jenkins without setting up the webhook in SonarQube. However, if the processing takes time in the subsequent analysis, your project will be stuck in the IN-PROGRESS state as you haven’t setup any mechanism for SonarQube server to inform Jenkins that the analysis report is ready.
What is a Webhook secret and how to configure it
If you want to verify the webhook payload that is sent to Jenkins, you can provide a secret while creating the webhook in SonarQube as shown in Image 4. If you have an existing webhook, you can update it by clicking the Update link on the extreme right as shown in Image 5 and then provide the secret text in the Update webhook screen. Next you need to configure the same secret in Jenkins. To do this go to Configure System > SonarQube Servers > Advanced > Webhook Secret and create a credential with the secret text as shown below.
Related post: SonarQube integration with Jenkins Pipeline
The secret text that you have setup in SonarQube should match the secret text in the Jenkins credential.
Congratulations, if you have been successful in configuring the webhook. If not, you may need to troubleshoot. Here are few known issues faced while creating webhooks.
Following are few of the known issues that are could be faced while setting up webhooks for which some guidance for their resolution is provided here. Click on the link stating the issue to view the resolution.
When we try to configure the webhook URL in SonarQube, we might come across this error. Refer the above link for guidance on resolution of this issue.
If we have run SonarQube analysis from a CI tool like Jenkins, we expect the task to be completed and the result of the analysis to be available, i.e. whether the Quality Gate status for our project is Passed or Failed. However, in some cases the task status remains as IN-PROGRESS.
The job keeps running with the same status till the timeout occurs or the job is manually stopped. In this case, either we haven’t configured the webhook or it hasn’t been configured properly. Refer the above link for guidance on resolution of this issue.
In this post we have discussed the role of Webhooks and how they can be configured in SonarQube. We have then walked through the advantage of webhooks w.r.t. Jenkins as the CI tool. After that we have seen the role of webhook secrets and how to configure them. Finally we have then gone through a few common issues that one might face while configuring webhooks and guidance to help with their resolution.
Let us know if you found this post helpful.