API รายงาน SonarQube และ Webhooks

บทความนี้อธิบายวิธีการเข้าถึงรายงานความปลอดภัย SonarQube ที่จัดเก็บในแพลตฟอร์ม Procurize โดยโปรแกรม จะครอบคลุม REST API สำหรับการแสดงรายการและดึงข้อมูลรายงาน, การดาวน์โหลดไฟล์รายงาน, และการสมัครรับการแจ้งเตือน webhook เมื่อมีรายงานใหม่ถูกนำเข้า

ภาพรวม

โมดูลย่อย SonarQube Reports ช่วยให้องค์กรสามารถจัดเก็บและจัดการรายงานความปลอดภัยและคุณภาพโค้ดที่สร้างโดย SonarQube อย่างศูนย์กลาง แพลตฟอร์ม Procurize เปิดเผยข้อมูลนี้ผ่าน:

• REST API สำหรับดึงเมตาข้อมูลของรายงานที่จัดเก็บ
• จุดเชื่อมต่อสำหรับดาวน์โหลดไฟล์รายงานเป็นไฟล์ ZIP
• Webhooks สำหรับแจ้งเตือนแบบเรียลไทม์เมื่อมีรายงานใหม่พร้อมใช้งาน

ความสามารถเหล่านี้ทำให้สามารถผสานรวมกับ pipeline CI/CD, ระบบ GRC, แดชบอร์ดภายใน, และเครื่องมือจัดการความเสี่ยงของบุคคลที่สามได้

การตรวจสอบสิทธิ์และการอนุญาต

คำขอ API ทั้งหมดที่อธิบายในบทความนี้ไม่ต้องการการตรวจสอบสิทธิ์

Organization ID

ต้องระบุ Organization ID สำหรับคำขอทั้งหมดที่อธิบายไว้ที่นี่
คุณสามารถค้นหาได้ใน แผงการตั้งค่าองค์กร ที่ https://dashboard.procurize.ai
โปรดทราบว่าการเข้าถึงแผงการตั้งค่าต้องมีการอนุมัติ และต้องมีบทบาทผู้ใช้อย่างน้อยเป็นผู้ดูแลระบบในองค์กรนั้น

Base URL

ทุกจุดเชื่อมต่อของ REST API ให้บริการภายใต้ Base URL ดังต่อไปนี้

https://api.procurize.com

SonarQube Reports REST API

รายการรายงาน

ดึงรายการรายงานความปลอดภัย SonarQube ที่จัดเก็บในแพลตฟอร์มแบบแบ่งหน้า

Endpoint

GET /security/report/list

พารามิเตอร์ Query

• org (required): Organization ID
• version (optional): เวอร์ชันที่ตรงกับผลิตภัณฑ์ในรูปแบบ Semantic Versioning
• minver (optional): เวอร์ชันขั้นต่ำของผลิตภัณฑ์ในรูปแบบ Semantic Versioning
• maxver (optional): เวอร์ชันสูงสุดของผลิตภัณฑ์ในรูปแบบ Semantic Versioning

โปรดทราบว่าต้องระบุอย่างน้อยหนึ่งในพารามิเตอร์ version, minver หรือ maxver สำหรับการร้องขอ

ตัวอย่างคำขอ

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

ตัวอย่างการตอบกลับ

{
  "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"
    }
  ]
}

ดาวน์โหลดไฟล์รายงาน (Archive)

ดาวน์โหลดไฟล์ ZIP ที่บรรจุไฟล์ผลลัพธ์ SonarQube ทั้งหมด ไฟล์นี้รวมรายงาน HTML และ PDF

Endpoint

GET /security/report/files

• org (required): Organization ID
• reports (required): อาร์เรย์ของ ID รายงาน

ตัวอย่างคำขอ

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"

การตอบกลับ

• Content‑Type: application/zip
• เนื้อหาตอบกลับเป็นไฟล์ ZIP ไบนารี

ไคลเอนต์ควรสตรีมการตอบกลับและบันทึกลงดิสก์

การจัดการข้อผิดพลาด

API ใช้รหัสสถานะ HTTP มาตรฐาน

• 200 OK: คำขอสำเร็จ
• 204 No Content: รายงานไม่มีอยู่
• 400 Bad Request: พารามิเตอร์ไม่ถูกต้องหรือคำขอมีรูปแบบผิด
• 500 Internal Server Error: ข้อผิดพลาดของเซิร์ฟเวอร์ที่ไม่คาดคิด

การตอบกลับข้อผิดพลาดจะมีโค้ดข้อผิดพลาดที่เครื่องอ่านได้และข้อความที่มนุษย์อ่านได้

Webhooks

Webhook ของ Procurize ช่วยระบบภายนอกรับการแจ้งเตือนเมื่อมีรายงาน SonarQube ใหม่ถูกนำเข้าหรืออัปเดต

การกำหนดค่า Webhooks

สามารถเพิ่มหรือแก้ไข Webhook ได้ใน แผงการตั้งค่าองค์กร ส่วน Security reports ที่ https://dashboard.procurize.ai
โปรดทราบว่าการเข้าถึงแผงการตั้งค่าต้องมีการอนุมัติ และต้องมีบทบาทผู้ใช้อย่างน้อยเป็นผู้ดูแลระบบในองค์กรนั้น

หากต้องการทดสอบ Webhook สามารถใช้บริการออนไลน์ยอดนิยมเช่น https://webhook-test.com

Payload ของ Webhook

Webhook จะส่งเป็น HTTP POST พร้อม payload ในรูปแบบ JSON

ตัวอย่าง 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"
    }
  ]
}

ความปลอดภัยของ Webhook

เพื่อให้แน่ใจว่าข้อความมาจากแหล่งที่เชื่อถือได้ Webhook จะส่งหัวข้อลายเซ็นที่สร้างจาก secret ร่วมกัน

• ลายเซ็นคำนวณด้วย HMAC‑SHA256
• ไคลเอนต์ควรตรวจสอบลายเซ็นก่อนประมวลผล payload

วิธีนี้ป้องกันการส่ง Webhook ที่ไม่ได้รับอนุญาตหรือปลอมแปลง

การส่งและการลองใหม่

• Webhook ต้องได้รับการตอบกลับสถานะ 2xx เพื่อถือว่าการส่งสำเร็จ
• หากส่งล้มเหลว ระบบจะลองใหม่ทุกชั่วโมงโดยอัตโนมัติ
• เหตุการณ์อาจถูกส่งหลายครั้ง; ผู้รับควรออกแบบการประมวลผลให้เป็น idempotent

กรณีการใช้งานทั่วไป

• ดึงข้อมูลการตรวจพบของ SonarQube ไปยังแดชบอร์ดความปลอดภัยภายในอัตโนมัติ
• เรียกใช้กระบวนการปฏิบัติตามเมื่อประตูคุณภาพ (quality gates) ล้มเหลว
• เก็บสำรองรายงานความปลอดภัยเพื่อใช้ในการตรวจสอบและการประเมินความเสี่ยงของผู้ขาย
• ทำให้ระบบของบุคคลที่สามซิงค์กับสถานะความปลอดภัยของโค้ดล่าสุดเสมอ