API y Webhooks de Informes de SonarQube

Este artículo describe cómo acceder programáticamente a los informes de seguridad de SonarQube almacenados en la plataforma Procurize. Cubre la API REST para listar y obtener informes, descargar archivos de informe y suscribirse a notificaciones webhook cuando se ingieren nuevos informes.

Visión general

El submódulo de Informes de SonarQube permite a las organizaciones almacenar y gestionar centralmente los informes de seguridad y calidad de código generados por SonarQube. La plataforma Procurize expone estos datos a través de:

Una API REST para obtener metadatos sobre los informes almacenados
Un punto final para descargar los artefactos de informe como archivos ZIP
Webhooks para notificaciones casi en tiempo real cuando nuevos informes están disponibles

Estas capacidades facilitan integraciones con pipelines CI/CD, sistemas GRC, paneles internos y herramientas de gestión de riesgos de terceros.

Autenticación y autorización

Todas las solicitudes de API descritas en este artículo no requieren autenticación.

ID de organización

Se requiere un ID de organización para todas las solicitudes descritas aquí.
Puede encontrarlo en el panel de configuración de la organización en https://dashboard.procurize.ai.
Tenga en cuenta que el acceso al panel de configuración requiere autorización, y el acceso al panel de configuración de la organización requiere un rol de usuario de al menos Administrador en esa organización.

Botón de copiar ID

URL base

Todos los puntos finales de la API REST se sirven bajo la siguiente URL base:

https://api.procurize.com

API REST de Informes de SonarQube

Listar informes

Obtiene una lista paginada de los informes de seguridad de SonarQube almacenados en la plataforma.

Punto final

GET /security/report/list

Parámetros de consulta

org (obligatorio): ID de la organización.
version (opcional): La versión exacta de los productos en formato SemVer.
minver (opcional): La versión mínima de los productos en formato SemVer.
maxver (opcional): La versión máxima de los productos en formato SemVer.

Tenga en cuenta que al menos uno de los parámetros version, minver o maxver es obligatorio para la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Producto de prueba",
      "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"
    }
  ]
}

Descargar archivo de informe

Descarga un archivo ZIP que contiene los artefactos completos del informe de SonarQube. El archivo incluye los informes en HTML y PDF.

Punto final

GET /security/report/files

org (obligatorio): ID de la organización.
reports (obligatorio): Array de IDs de informes.

Ejemplo de solicitud

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"

Respuesta

Content-Type: application/zip
El cuerpo de la respuesta contiene el archivo ZIP binario

Los clientes deben transmitir la respuesta y guardarla en disco.

Manejo de errores

La API utiliza códigos de estado HTTP estándar.

200 OK: Solicitud exitosa
204 No Content: El informe no existe
400 Bad Request: Parámetros inválidos o solicitud malformada
500 Internal Server Error: Error inesperado del servidor

Las respuestas de error incluyen un código de error legible por máquina y un mensaje legible por humanos.

Webhooks

Los webhooks de Procurize permiten que sistemas externos reciban notificaciones cuando se ingieren o actualizan nuevos informes de SonarQube.

Configuración de webhooks

Los webhooks pueden añadirse o editarse en el panel de configuración de la organización, sección Informes de seguridad, en https://dashboard.procurize.ai.
Tenga en cuenta que el acceso al panel de configuración requiere autorización, y el acceso al panel de configuración de la organización requiere un rol de usuario de al menos Administrador en esa organización.

Editor de webhooks

Para probar webhooks, puede usar servicios en línea como https://webhook-test.com.

Carga útil del webhook

Los eventos de webhook se entregan como solicitudes HTTP POST con una carga útil JSON.

Ejemplo de carga útil

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Producto de prueba",
      "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"
    }
  ]
}

Seguridad del webhook

Para garantizar la autenticidad, las solicitudes de webhook incluyen un encabezado de firma generado con un secreto compartido.

La firma se calcula usando HMAC‑SHA256
Los clientes deben verificar la firma antes de procesar la carga útil

Esto previene entregas de webhook no autorizadas o falsificadas.

Entrega y reintentos

Los webhooks esperan una respuesta 2xx para considerarse entregados correctamente.
Los intentos fallidos se reintentan automáticamente cada hora.
Los eventos pueden entregarse más de una vez; los consumidores deben implementar procesamiento idempotente.

Casos de uso típicos

Ingerir automáticamente los hallazgos de SonarQube en paneles internos de seguridad.
Activar flujos de trabajo de cumplimiento cuando fallan los gates de calidad.
Archivar informes de seguridad para auditorías y revisiones de riesgos de proveedores.
Mantener sincronizados los sistemas de terceros con la postura de seguridad del código más reciente.