Webhook Events
DevGuard can send HTTP POST requests to a URL of your choice whenever specific security events occur. Use webhooks to integrate DevGuard with external systems such as notification services, SIEMs, ticketing tools, or custom automation pipelines.
Supported Event Types
| Type | Description | Triggered when |
|---|---|---|
sbom | Software Bill of Materials | A new SBOM is generated for an asset version |
dependencyVulnerabilities | Dependency vulnerabilities | New dependency vulnerabilities are detected (SCA) |
firstPartyVulnerabilities | First-party vulnerabilities | New first-party vulnerabilities are detected (SAST) |
test | Test event | A test webhook is sent manually from the UI or API |
Webhook Scope
Webhooks can be registered at two levels:
- Organization level — receives events for all projects within the organization.
- Project level — receives events only for assets within that specific project.
When an event fires, DevGuard delivers it to all matching webhooks: project-scoped webhooks for that project and organization-scoped webhooks.
Creating a Webhook
Via the API
For a project-scoped webhook:
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | Display name for the webhook |
description | string | no | Description of the webhook's purpose |
url | string | yes | The endpoint URL that will receive the POST requests |
secret | string | no | Shared secret sent as the X-Webhook-Secret header for verification |
sbomEnabled | boolean | no | Enable delivery of SBOM events |
vulnEnabled | boolean | no | Enable delivery of vulnerability events (dependency & first-party) |
Example Response:
Updating a Webhook
The request body is the same as creation, but must also include the id field.
Deleting a Webhook
Payload Format
Every webhook delivery is an HTTP POST with Content-Type: application/json. The payload follows this structure:
The payload field contains the event-specific data and varies by event type:
sbom— A full CycloneDX BOM object.dependencyVulnerabilities— An array of dependency vulnerability objects including CVE details, component purl, CVSS score, risk assessment, and fix version.firstPartyVulnerabilities— An array of first-party vulnerability objects including rule ID, file URI, code snippet, scanner ID, and severity.test— A simple object with amessageandtimestamp.
Verifying Webhook Deliveries
If you configured a secret when creating the webhook, DevGuard includes it in every request to your endpoint as:
X-Webhook-Secret: <your-secret>
Your endpoint should validate this header to ensure the request originates from DevGuard.
The following example shows how this could look like in your backend server.
Example usage of webhook secret (Node.js / Express):
Retry Behavior
If your endpoint does not return a 2xx status code, DevGuard retries the delivery up to 3 times with increasing delays: 1 second, 5 seconds, and 10 seconds.
Requests time out after 120 seconds.
Testing a Webhook
You can send a test payload to any URL without saving it:
Request Body:
DevGuard will take the URL you provided and send a test-payload to it to verify the webhook integration.
Supported payloadType values:
| Value | Description |
|---|---|
empty | Simple test message with a timestamp |
sampleSbom | A sample CycloneDX SBOM |
sampleDependencyVulns | A sample dependency vulnerability (CVE-2021-44228) |
sampleFirstPartyVulns | A sample first-party vulnerability (SQL injection) |