Guide to SonarQube Webhooks: Features and Best Practices
SonarQube Server is SonarSource's self-hosted server for code quality and security analysis. When a scanner run finishes and the background task completes, SonarQube can POST the result, including the quality gate verdict, to any URL you register. Teams use this to stop a deployment on a failed gate, post results to chat, or open a ticket for the project owner.
This guide covers how SonarQube webhooks are scoped to projects or the whole instance, what the analysis payload contains, how to verify the optional X-Sonar-Webhook-HMAC-SHA256 signature, and how to cope with a sender that times out after 10 seconds and never retries.
What are SonarQube webhooks?
A SonarQube webhook is a name, a URL and an optional Secret. Project administrators can add up to 10 per project, and global administrators can add webhooks that fire for every project. All of them fire: a project with two webhooks and an instance with one global webhook sends three requests per analysis.
There's no event list to subscribe to. Every delivery is the same payload, sent in two situations: when an analysis completes, and when a change to an issue flips the project's quality gate status. The payload doesn't say which of the two caused it.
Because SonarQube is self-hosted, every instance is its own sender, with whatever egress address its host has. The server also refuses webhook URLs that resolve to internal addresses unless an administrator turns off that validation.
SonarQube webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | x-sonar-webhook-hmac-sha256 |
| Body | JSON |
Events and payloads
qualityGate.status | Triggered When | Common Use Cases |
|---|---|---|
OK | The analysis passed the quality gate | Promote a build, post a success message |
ERROR | The analysis failed the quality gate | Block a deploy, notify the owner, open a ticket |
Payload Structure
The body is UTF-8 JSON with these top-level fields:
| Field | Meaning |
|---|---|
serverUrl | Base URL of the SonarQube instance |
taskId | ID of the background task that processed the analysis |
status | State of that task, not the quality gate |
analysedAt | When the analysis ran |
revision | The analysed commit |
project | The project, including its key and name |
qualityGate | The gate's name, overall status and its conditions |
properties | sonar.analysis.* parameters passed to the scanner |
Use qualityGate.status for pass or fail decisions and the top-level status only to check that the task itself succeeded. properties is the place to carry your own data through, such as a build number or pipeline ID set with -Dsonar.analysis.buildId=... on the scanner. Branch and pull request analyses can include fields that the docs example doesn't show, so parse defensively.
Each request also carries an X-SonarQube-Project header with the project key, which is handy for routing before you parse the body.
Setting up SonarQube webhooks
Prerequisites
- Administer rights on the project, or global administration for an instance-wide webhook
- An endpoint the SonarQube server can reach that doesn't resolve to an internal address (use the Hookdeck CLI locally)
Set a Secret
Set a secret on the SonarQube webhook. Without one, deliveries are unsigned and fail verification.
The X-Sonar-Webhook-HMAC-SHA256 header is only sent when the webhook has a Secret. Pick a long random string, store it as WEBHOOK_SECRET, and use its UTF-8 bytes as the HMAC key with no decoding.
Register Your Endpoint
- Open the project and go to Project Settings > Webhooks, or use Administration > Configuration > Webhooks for a global webhook.
- Click Create.
- Enter a Name and the URL, for example
https://your-server.com/webhooks/sonarqube. - Enter the random string in Secret.
- Save.
The same settings can be scripted with the api/webhooks Web API, which is the practical route when many projects need the same webhook.
Alternative: Basic Auth in the URL
SonarQube also accepts credentials in the URL, as in https://myLogin:myPassword@my_. That only proves the caller knew the password. The Secret signs the body, so prefer it, and use Basic auth only when a receiver can't compute an HMAC.
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
npx hookdeck-cli listen 3000 sonarqube --path /webhooks/sonarqube
Add the CLI's public URL as a project webhook, then run a scanner analysis on that project. The first delivery shows the properties your pipeline passes and the exact qualityGate shape for your server version.
Securing SonarQube webhooks
The header holds a bare 64-character hex digest with no prefix. Compute HMAC-SHA256 over the raw body with the Secret, then compare the two digests in constant time. Nothing else is signed: there's no timestamp, so a captured request stays valid and you should treat repeats as possible. See the webhook documentation.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-sonar-webhook-hmac-sha256'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
SonarQube sends no event or delivery ID, so the handler below uses a hash of the body as its deduplication key. That treats an analysis result and a later gate change as separate deliveries, since their bodies differ, while catching an exact redelivery. Because SonarQube never retries, the handler stores the result and responds before doing anything slow.
const express = require('express');
function createSonarQubeApp({ store, onGateFailed, onGatePassed }) {
const app = express();
app.post('/webhooks/sonarqube', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const deliveryKey = crypto.createHash('sha256').update(req.body).digest('hex');
const projectKey = req.headers['x-sonarqube-project'];
let parsed;
try {
parsed = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
const { taskId, qualityGate } = parsed;
if (!qualityGate || typeof qualityGate !== 'object') return res.sendStatus(400);
try {
const isNew = await store(deliveryKey, projectKey, req.body);
if (isNew && qualityGate?.status === 'ERROR') await onGateFailed(projectKey, taskId);
else if (isNew && qualityGate?.status === 'OK') await onGatePassed(projectKey, taskId);
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
Keep onGateFailed and onGatePassed quick (enqueue a job rather than calling a slow API), since anything past 10 seconds counts as a failed delivery that won't come back.
Hookdeck's SonarQube source computes the same HMAC over the body and compares it with the header. SonarQube always gets a 200 from Hookdeck. When the digest doesn't match, the request is marked as failed verification and goes no further. If you've deliberately left the Secret empty, leave verification off on the source instead.
Don't lose quality gate results. Hookdeck Event Gateway gives SonarQube a public URL that answers inside the timeout, verifies the signature, and retries delivery to your service, which SonarQube itself never does.
SonarQube webhook limitations and pain points
No retries
The Problem: One timeout or error and the result is gone from the receiver's point of view.
Why It Happens: A delivery that doesn't get a response within 10 seconds fails, and SonarQube doesn't retry failed deliveries. The records are kept for 30 days.
Workarounds:
- Respond fast and move processing to a queue.
- Check the delivery records after an outage and redeliver through the Web API, or read the project's quality gate status from the API.
How Hookdeck Can Help: Hookdeck accepts the request at once and then retries your endpoint on a schedule you set, with manual replay for anything that still fails.
No event type or delivery ID
The Problem: You can't tell an analysis result from a gate change caused by an issue update, or recognise a duplicate by ID.
Why It Happens: Both triggers send the same payload, and there's no event type field or delivery ID header.
Workarounds:
- Hash the body for deduplication.
- Compare
analysedAtandqualityGate.statuswith what you last stored for the project to see what changed.
How Hookdeck Can Help: Hookdeck gives every request its own ID, keeps the full body, and can drop exact duplicates before forwarding.
Signing is optional
The Problem: A webhook created without a Secret sends unsigned requests, and nothing warns you.
Why It Happens: The Secret field is optional in both the UI and the Web API.
Workarounds:
- Make the Secret part of whatever script or checklist creates webhooks.
- Audit existing webhooks with the Web API.
How Hookdeck Can Help: With verification on, an unsigned delivery shows up as a failed verification instead of reaching your service.
Overlapping project and global webhooks
The Problem: The same analysis reaches a receiver more than once.
Why It Happens: Project and global webhooks all fire, so a URL registered at both levels gets two requests.
Workarounds:
- Register each URL at one level only.
- Keep body-hash deduplication in place regardless.
How Hookdeck Can Help: Deduplication on the Hookdeck connection drops the second copy before it reaches you.
Internal URLs are rejected
The Problem: You can't point SonarQube at a service on the same private network without changing server settings.
Why It Happens: SonarQube rejects webhook URLs that resolve to internal addresses unless an administrator disables the check.
Workarounds:
- Expose a public, authenticated endpoint for the webhook.
- If you disable the validation, restrict which administrators can create webhooks.
How Hookdeck Can Help: The Hookdeck source URL is public, so it passes SonarQube's check without a settings change, and your receiver only has to accept traffic from Hookdeck.
Best practices
Carry pipeline context in properties
Pass a build or pipeline ID with sonar.analysis.* scanner parameters. It comes back in properties, which is how you link a webhook to the CI job waiting on it.
Decide on qualityGate.status
Gate deployments on qualityGate.status, not the task status, and treat any unknown value as a failure.
Use one webhook per consumer
A Secret is per webhook, so separate consumers can have separate secrets and can be removed independently. Stay within the 10-per-project limit by sending to a single Hookdeck source and fanning out from there.
Pin to your server version
The payload is set by the SonarQube release, with no version field. Re-check a captured delivery after upgrading the server.
Conclusion
SonarQube's webhook is simple: one payload, one optional signature header and per-project or global scope. What it lacks is delivery assurance. There are no retries, no event type and no delivery ID, so the receiver has to be quick, deduplicate on content and have a way to recover a missed result.
Hookdeck Event Gateway supplies the retries, deduplication and replay SonarQube leaves out.
Get started with Hookdeck for free and handle SonarQube webhooks reliably in minutes.