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#

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#

POST /api/v1/organizations/{org}/integrations/webhook/test-and-save/

For a project-scoped webhook:

POST /api/v1/organizations/{org}/projects/{project}/integrations/webhook/test-and-save/

Request Body:

{
  "name": "My SIEM Integration",
  "description": "Forward vulnerability events to our SIEM",
  "url": "https://example.com/devguard-webhook",
  "secret": "my-shared-secret",
  "sbomEnabled": true,
  "vulnEnabled": true
}

Example Response:

{
  "id": "a1b2c3d4-...",
  "name": "My SIEM Integration",
  "description": "Forward vulnerability events to our SIEM",
  "url": "https://example.com/devguard-webhook",
  "sbomEnabled": true,
  "vulnEnabled": true
}

Updating a Webhook#

PUT /api/v1/organizations/{org}/integrations/webhook/{id}/

The request body is the same as creation, but must also include the id field.

Deleting a Webhook#

DELETE /api/v1/organizations/{org}/integrations/webhook/{id}/

Payload Format#

Every webhook delivery is an HTTP POST with Content-Type: application/json. The payload follows this structure:

{
  "type": "sbom | dependencyVulnerabilities | firstPartyVulnerabilities | test",
  "organization": {
    "id": "uuid",
    "name": "My Org",
    "slug": "my-org"
  },
  "project": {
    "id": "uuid",
    "name": "My Project",
    "slug": "my-project"
  },
  "asset": {
    "id": "uuid",
    "name": "My Asset",
    "slug": "my-asset",
    "description": "..."
  },
  "assetVersion": {
    "name": "main",
    "slug": "main",
    "defaultBranch": true,
    "type": "branch"
  },
  "artifact": {
    "artifactName": "my-image:latest"
  },
  "payload": "..."
}

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 a message and timestamp.

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):

app.post("/devguard-webhook", (req, res) => {
  const secret = req.headers["x-webhook-secret"];
  if (secret !== process.env.DEVGUARD_WEBHOOK_SECRET) {
    return res.status(401).send("Unauthorized");
  }

  const event = req.body;
  console.log(`Received ${event.type} event for ${event.asset.name}`);

  // Process the event...
  res.status(200).send("OK");
});

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:

POST /api/v1/organizations/{org}/integrations/webhook/test/

Request Body:

{
  "url": "https://example.com/devguard-webhook",
  "secret": "my-shared-secret",
  "payloadType": "sampleDependencyVulns"
}

DevGuard will take the URL you provided and send a test-payload to it to verify the webhook integration.

Supported payloadType values: