SonarQube Webhooks

A webhook is an automatic message. When something happens in SonarQube, the server sends a small data package to an address you choose. Build tools, chat apps, and dashboards use that message to react without constant checking.

The Doorbell Picture

Waiting for a parcel by opening the front door every minute wastes time. A doorbell tells you when it arrives. Without webhooks, a pipeline must ask SonarQube again and again whether the analysis finished. With webhooks, SonarQube rings the bell.

 Scanner uploads report
         │
         ▼
 SonarQube processes ──► analysis finished
         │
         │  POST (JSON message)
         ▼
 ┌──────────────────────────────┐
 │ Your receiver                │
 │  • Jenkins resumes the build │
 │  • Chat app posts a message  │
 │  • Dashboard updates         │
 └──────────────────────────────┘

When SonarQube Sends a Webhook

The server sends the message after the Compute Engine completes processing an analysis. The message arrives whether the quality gate passed or failed.

The Message Content

The body uses JSON format. These fields appear most often.

Field	Meaning
serverUrl	Address of the SonarQube server
taskId	ID of the finished background task
status	Task result, such as SUCCESS or FAILED
analysedAt	Time of the analysis
project	Project key, name, and link
qualityGate	Gate name, overall status, and each condition

Sample Message

{
  "taskId": "AY123abc",
  "status": "SUCCESS",
  "project": { "key": "shop-backend", "name": "Shop Backend" },
  "qualityGate": {
    "name": "Sonar way",
    "status": "ERROR",
    "conditions": [
      { "metric": "new_coverage", "status": "ERROR", "value": "62.5" }
    ]
  }
}

Create a Webhook

1. Open a project and go to Project Settings, then Webhooks. Administrators can also create global webhooks under Administration.
2. Click Create.
3. Enter a name, such as Team Chat Alert.
4. Enter the receiver URL.
5. Enter a secret if you want signed messages.
6. Save the webhook.

Protect the Receiver

Anyone who learns your receiver address could send fake messages. A secret solves this problem. SonarQube signs each message with the secret and places the signature in the X-Sonar-Webhook-HMAC-SHA256 header. The receiver recalculates the signature and rejects mismatches.

Popular Uses

Jenkins Quality Gate Step

The waitForQualityGate step in Jenkins pauses a pipeline until the webhook arrives. Without a configured webhook, the step waits until it times out.

Chat Alerts

A small service converts the message into a readable note for a team chat channel: project name, gate result, and a link to the dashboard.

Ticket Creation

A failed gate on the main branch can open a ticket in your tracking system, assigned to the team that owns the project.

Custom Dashboards

Teams store each message in a database and chart quality trends across many projects.

Check Delivery

The Webhooks page lists the latest delivery for each webhook, including the response code and the time. A green mark means the receiver answered successfully. A red mark means a timeout or an error status. Click the entry to view the full payload sent.

Troubleshooting

• Use a receiver that answers quickly. SonarQube waits only a short time for a reply.
• Allow the SonarQube server address through firewalls in both directions.
• Use HTTPS in production to protect the content in transit.
• Confirm that the receiver accepts the POST method and JSON content type.

A Practical Flow

A pipeline uploads a report and pauses. SonarQube finishes processing in thirty seconds and sends the webhook message to Jenkins. Jenkins reads the gate status, resumes the pipeline, and stops the deployment when the status shows an error. At the same moment a chat service posts a short note to the team channel. Nobody refreshed any page, and the whole chain finished in under a minute.

Global or Project Level

Global webhooks fire for every project and suit organization-wide alerts. Project webhooks fire for one project and suit team-specific tools. Mix both when needed, and name each webhook clearly so owners can find it later.

Quick Recap

Webhooks let SonarQube announce finished analyses. Create one in settings, add a secret, and connect it to the tools that need the news.