Agent skill
SonarQube Webhooks Skill
Receive and verify SonarQube webhooks. Use when setting up a SonarQube Server webhook for analysis results, verifying the X-Sonar-Webhook-HMAC-SHA256 header (bare hex HMAC-SHA256 of the raw body keyed with the webhook Secret), debugging signature verification failures, or handling quality gate results (qualityGate.status OK or ERROR).
Install this skill
npx skills add hookdeck/webhook-skills --skill sonarqube-webhooks
When to Use This Skill
- How do I receive SonarQube webhooks when an analysis finishes?
- How do I verify the SonarQube
X-Sonar-Webhook-HMAC-SHA256header? - How do I react to a failed quality gate (
qualityGate.statusofERROR)? - Why is my SonarQube webhook signature verification failing, or why is there no signature header at all?
- How do I secure a SonarQube webhook with a Secret?
Set a secret on the SonarQube webhook. Without one, deliveries are unsigned and fail verification.
Verification (core)
SonarQube sends X-Sonar-Webhook-HMAC-SHA256: the bare lowercase hex HMAC-SHA256 of the raw request body, keyed with the webhook's Secret (its UTF-8 bytes, used as-is). There is no prefix, no timestamp and no id in the signed content, and the header is only sent when a Secret is set. Verify the raw bytes before parsing JSON, and compare the whole header value as one digest.
const crypto = require('crypto');
function verifySonarQubeSignature(rawBody, signature, secret) {
// Check shape first: Buffer.from(x, 'hex') silently drops invalid characters
if (!signature || !secret || !/^[0-9a-f]{64}$/i.test(signature)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature.toLowerCase()));
}
import hashlib, hmac, re
def verify_sonarqube_signature(raw_body: bytes, signature, secret) -> bool:
if not signature or not secret or not re.fullmatch(r"[0-9a-fA-F]{64}", signature):
return False
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), signature.lower().encode())
Return 401 for a missing, empty, malformed or mismatched header. Read the body as bytes (express.raw({ type: '*/*' }), await request.arrayBuffer(), await request.body()) so any content type works.
For complete handlers with route wiring, event dispatch, and tests, see:
Events and Payload
SonarQube has no event-name field or header. Every delivery is an analysis result, a POST with a JSON body containing taskId, status, analysedAt, project, qualityGate and properties. Branch on qualityGate.status:
qualityGate.status | Meaning |
|---|---|
OK | Quality gate passed |
ERROR | Quality gate failed |
Delivery Behavior
- A delivery fails if your URL does not respond within 10 seconds.
- Failed deliveries are never retried (redeliver through the Web API if needed). Respond fast and process asynchronously.
- Delivery records are kept for 30 days.
- A project can have up to 10 webhooks, and global webhooks also fire. SonarQube is self-hosted, so each instance is its own sender.
- Besides the HMAC, SonarQube supports basic auth credentials in the webhook URL (
https://user:password@host/path).
Environment Variables
SONARQUBE_WEBHOOK_SECRET=your_webhook_secret # The Secret field of the SonarQube webhook
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 sonarqube --path /webhooks/sonarqube
Reference Materials
- references/overview.md - SonarQube webhook concepts and payload
- references/setup.md - Configuration guide
- references/verification.md - Signature verification details