Guide to configure a webhook in SonarQube
Overview
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.
Topics Covered
Below is the sequence in which we will proceed. Feel free to jump to any sub topic of your interest.
- Section 1-
- Section2-
- 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:
👉 How to Install SonarQube 9 on windows with tips for troubleshooting
👉 How to install SQL Server database for 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.
Troubleshooting
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.
1. Invalid URL: loopback and wildcard addresses are not allowed for webhooks.
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.
2. How to handle inprogress status for Sonarqube Quality gate
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.
Summary
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.
Hello Rajesh, Thanks for your response. The secret in SonarQube webhooks is a random string of your choice. Configuring a secret is optional. If you do choose to configure it, then the same secret string should be configured in Jenkins as well.
Hi Saran/Team,
The issue I am facing is after analysis is completed in SQ the quality gate status result is not sent to Jenkins by Webhook . Checked in Webhook last delivery status it says Response: Server unreachable. In Jenkins console o/p it says IN PROGRESS and get timeout as per specified time. Below are the steps i have done. Please advise how to fix it.
1. Configured the Webhook in SQ. project settings….. https://jenkins-****-****-****.****.***/sonarqube-webhook/
2. created a secret in Jenkins and gave an ID to the secret in our project folder by doing add credentials and same secret i gave in SQ Webhook. bcoz In my company its not allowed to create like below.
Go to _Manage Jenkins_ -> _Configure System_ -> _SonarQube servers_ -> _Advanced…_
– Set _Webhoot Secret_ to _SonarQube webhook secret_
3. In pipeline i use like this waitForQualityGate(webhookSecretId: ‘yourSecretID’)
stage(“Quality Gate”) {
steps {
timeout(time: 30, unit: ‘MINUTES’) {
waitForQualityGate abortPipeline: true
script {
def qg=waitForQualityGate(webhookSecretId: ‘yoursecretid’)
if(qg.status != ‘OK’) {
error “Pipeline aborted due to quality gate failed: ${qg.status}”
“Server Unreachable” error in SonarQube is usually straight forward meaning the url configured in webhook is unreachable.
This could be because of firewall, unopened port, etc. I had come across this “Server Unreachable” error when I had moved SonarQube to a different server which did not have the host name entry for the Jenkins server url mentioned in the webhook. So it was obvious that webhook was unable to reach the Jenkins server. It was fixed once an entry was made in the hosts file. Let me know what worked for you.
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
============================================
Thanks for clear explanation. With reference to above ,I have one doubt where i will get this secret?
will appreciate the quick reply.