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-SHA256 header?
  • How do I react to a failed quality gate (qualityGate.status of ERROR)?
  • 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.statusMeaning
OKQuality gate passed
ERRORQuality 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →