API dei report SonarQube e Webhook

Questo articolo descrive come accedere programmaticamente ai report di sicurezza SonarQube memorizzati nella piattaforma Procurize. Copre l’API REST per elencare e recuperare i report, scaricare gli archivi dei report e iscriversi alle notifiche webhook quando vengono importati nuovi report.

Panoramica

Il sotto-modulo SonarQube Reports consente alle organizzazioni di archiviare e gestire centralmente i report di sicurezza e di qualità del codice generati da SonarQube. La piattaforma Procurize espone questi dati tramite:

Un’API REST per recuperare i metadati dei report archiviati
Un endpoint per scaricare gli artefatti dei report in archivi ZIP
Webhook per notifiche quasi in tempo reale quando nuovi report sono disponibili

Queste funzionalità abilitano integrazioni con pipeline CI/CD, sistemi GRC, dashboard interne e strumenti di gestione del rischio di terze parti.

Autenticazione e Autorizzazione

Tutte le richieste API descritte in questo articolo non richiedono autenticazione.

ID organizzazione

Un ID organizzazione è necessario per tutte le richieste descritte qui.
Puoi trovarlo nel pannello impostazioni dell’Organizzazione su https://dashboard.procurize.ai.
Si noti che l’accesso al pannello impostazioni richiede autorizzazione e l’accesso al pannello impostazioni dell’organizzazione richiede un ruolo utente di almeno Amministratore in tale organizzazione.

Pulsante Copia ID

URL di base

Tutti gli endpoint API REST sono serviti sotto il seguente URL di base:

https://api.procurize.com

API REST dei report SonarQube

Elenca report

Recupera un elenco paginato di report di sicurezza SonarQube archiviati nella piattaforma.

Endpoint

GET /security/report/list

Parametri di query

org (obbligatorio): ID organizzazione.
version (opzionale): La versione esatta dei prodotti nel formato Semantic Versioning.
minver (opzionale): La versione minima dei prodotti nel formato Semantic Versioning.
maxver (opzionale): La versione massima dei prodotti nel formato Semantic Versioning.

Si noti che almeno uno dei parametri version, minver o maxver è richiesto per la richiesta.

Esempio di richiesta

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"

Esempio di risposta

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Scarica archivio report

Scarica un archivio ZIP contenente gli artefatti completi del report SonarQube. L’archivio include report HTML e PDF.

Endpoint

GET /security/report/files

org (obbligatorio): ID organizzazione.
reports (obbligatorio): Array di ID report.

Esempio di richiesta

curl "https://api.procurize.com/security/report/files?org=00000000-0000-0000-0000-000000000001&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003"

Risposta

Content‑Type: application/zip
Il corpo della risposta contiene il file ZIP binario

I client dovrebbero eseguire lo streaming della risposta e salvarla su disco.

Gestione degli errori

L’API utilizza i codici di stato HTTP standard.

200 OK: Richiesta completata con successo
204 No Content: Report non esiste
400 Bad Request: Parametri non validi o richiesta malformata
500 Internal Server Error: Errore interno del server inaspettato

Le risposte di errore includono un codice di errore leggibile dalla macchina e un messaggio leggibile dall’utente.

Webhook

I webhook di Procurize consentono ai sistemi esterni di ricevere notifiche quando nuovi report SonarQube vengono importati o aggiornati.

Configurazione dei webhook

I webhook possono essere aggiunti o modificati nel pannello impostazioni dell’Organizzazione, sezione Security reports su https://dashboard.procurize.ai.
Si noti che l’accesso al pannello impostazioni richiede autorizzazione e l’accesso al pannello impostazioni dell’organizzazione richiede un ruolo utente di almeno Amministratore in tale organizzazione.

Editor Webhook

Per verificare i webhook, puoi utilizzare servizi online popolari come https://webhook-test.com

Payload del webhook

Gli eventi webhook sono consegnati come richieste HTTP POST con un payload JSON.

Esempio di payload

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Sicurezza del webhook

Per garantire l’autenticità, le richieste webhook includono un header di firma generato usando un segreto condiviso.

La firma è calcolata usando HMAC‑SHA256
I client dovrebbero verificare la firma prima di elaborare il payload

Ciò previene consegne di webhook non autorizzate o falsificate.

Consegna e ritentativi

I webhook si considerano consegnati correttamente se ricevono una risposta 2xx
Le consegne non riuscite vengono ritentate automaticamente ogni ora.
Gli eventi possono essere consegnati più di una volta; i consumatori dovrebbero implementare un’elaborazione idempotente

Casi d’uso tipici

Ingerire automaticamente i risultati SonarQube nei dashboard di sicurezza interni
Attivare flussi di lavoro di conformità quando i gate di qualità falliscono
Archiviare i report di sicurezza per audit e revisioni del rischio dei fornitori
Mantenere sincronizzati i sistemi di terze parti con lo stato più recente della sicurezza del codice