Webhooks - ZeroPath Documentation

Overview

ZeroPath webhooks allow you to receive real-time HTTP notifications when important security events occur in your repositories. This enables you to build custom integrations, automate workflows, and stay informed about your security posture.

Quick Setup

Configure webhooks in your Organization Settings to start receiving real-time security notifications.

How Webhooks Work

When a subscribed event occurs, ZeroPath sends an HTTP POST request to your configured endpoint with a JSON payload containing detailed information about the event. You can use this data to:

Automate Security Workflows: Trigger automated responses to security events
Build Custom Integrations: Connect ZeroPath with your existing tools and platforms
Monitor Security Posture: Track vulnerabilities and scan results in real-time
Enhance Compliance: Log security events for audit trails

Supported Event Types

ZeroPath supports the following webhook event types:

SCAN_STARTED

When a full repository scan begins

SCAN_COMPLETE

When a full repository scan finishes successfully

SCAN_FAILED

When a scan fails to complete

SCAN_SCHEDULED

When a scan is scheduled

PR_SCAN_STARTED

When a pull request scan begins

PR_SCAN_COMPLETE

When a pull request scan completes

NEW_VULNERABILITIES_FULL_SCAN

When new vulnerabilities are detected in a full repository scan

NEW_VULNERABILITIES_PR

When new vulnerabilities are detected in a pull request

VULNERABILITY_PATCHED

When a vulnerability is fixed

VULNERABILITY_REOPENED

When a vulnerability reappears

PR_BLOCKED

When a pull request is blocked due to vulnerabilities

PR_MERGED_WITH_ISSUES

When a pull request is merged to main branch with open vulnerabilities

REPORT_COMPLETE

When a report is generated

LONG_RUNNING_SCAN

When a scan is taking unusually long

AUDIT_LOG_EVENT

Important audit log events

Webhook Payload Structure

All webhook payloads follow a consistent structure with event-specific data:

Common Fields

Field	Type	Required	Description
`event`	string	Yes	The type of event that triggered the webhook (e.g., `SCAN_COMPLETE`, `NEW_VULNERABILITIES_FULL_SCAN`)
`timestamp`	string	Yes	ISO 8601 timestamp of when the event occurred
`organization`	object	Yes	Organization information
`organization.id`	string	Yes	Unique identifier for the organization
`organization.name`	string	No	Name of the organization
`repository`	object	No	Repository information (present in repository-specific events)
`repository.id`	string	No	Unique identifier for the repository
`repository.name`	string	No	Name of the repository
`scan`	object	No	Scan information (present in scan-related events)
`scan.id`	string	No	Unique identifier for the scan
`scan.type`	string	No	Type of scan (e.g., `FullScan`, `PrScan`)
`scan.status`	string	No	Status of the scan
`scan.duration_minutes`	number	No	How long the scan took to complete
`scan.vulnerability_summary`	object	No	Summary of vulnerabilities found
`scan.vulnerability_summary.total`	number	No	Total number of vulnerabilities
`scan.vulnerability_summary.by_severity`	object	No	Breakdown by severity category
`scan.url`	string	No	URL to view scan results in ZeroPath dashboard
`error`	string	No	Error message (present in failure events)
`metadata`	object	No	Additional event-specific data
`audit_log`	object	No	Audit log details (present in `AUDIT_LOG_EVENT`)
`audit_log.id`	string	No	Unique identifier for the audit log entry
`audit_log.endpoint`	string	No	API endpoint that was called
`audit_log.arguments`	any	No	Arguments passed to the API endpoint
`audit_log.caller`	object	No	Information about who triggered the action
`audit_log.timestamp`	string	No	When the audit event occurred
`vulnerability`	object	No	Detailed vulnerability information (present in vulnerability events)

Event Payload Examples

NEW_VULNERABILITIES_FULL_SCAN

This event is triggered when new vulnerabilities are discovered during a full repository scan:

{
  "type": "NEW_VULNERABILITIES_FULL_SCAN",
  "organizationId": "org_01K0B17A9B9BC0SMZP4QNA5EYX",
  "repositoryId": "8eb496c8-831f-428b-880b-cfe9d6a52b4f",
  "repositoryName": "Signal-Server",
  "scanId": "ece76dad-120c-415e-b261-7a1b8e7a32d5",
  "scanType": "FullScan",
  "vulnerabilityCount": 1,
  "vulnerabilitiesByScore": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 1,
    "info": 0
  },
  "vulnerability": {
    "id": "717a49cf-de6a-40dd-8beb-b32beb401189",
    "affectedFile": "service/src/main/java/com/example/AccountController.java",
    "generatedTitle": "Unbounded GCM id",
    "generatedDescription": "The handler accepts registrationId.gcmRegistrationId() and persists it without validation...",
    "score": 19,
    "severity": 2.3,
    "confidence": 8,
    "cvssScore": "CVSS:4.0/AV:N/AC:L/AT:P/PR:L/UI:N/VC:N/VI:N/VA:L/SC:N/SI:N/SA:L",
    "cwes": ["CWE-400"],
    "startLine": 94,
    "endLine": 115,
    "language": "java",
    "vulnClass": "Denial of Service (DOS)",
    "vulnCategory": "SAST",
    "status": "open",
    "discoveryTool": "ZeroPath SAST BL"
  }
}

NEW_VULNERABILITIES_PR

This event has the same structure as NEW_VULNERABILITIES_FULL_SCAN but is triggered for vulnerabilities found during pull request scans:

{
  "type": "NEW_VULNERABILITIES_PR",
  "organizationId": "org_01K0B17A9B9BC0SMZP4QNA5EYX",
  "repositoryId": "8eb496c8-831f-428b-880b-cfe9d6a52b4f",
  "repositoryName": "example-backend",
  "scanId": "scan-id",
  "scanType": "PrScan",
  "vulnerabilityCount": 2,
  "vulnerabilitiesByScore": {
    "critical": 0,
    "high": 1,
    "medium": 1,
    "low": 0,
    "info": 0
  },
  "metadata": {
    "prNumber": 123,
    "prTitle": "Add new authentication endpoint"
  },
  "vulnerability": { /* Same structure as FULL_SCAN */ }
}

Configuring Webhooks

Integrations

Add and manage webhook endpoints

Notifications

Configure which events trigger webhooks

Setting Up Webhooks

Webhook configuration in ZeroPath is a two-step process that gives you granular control over which events you receive:

Step 1: Add a Webhook Integration

Navigate to zeropath.com/app/settings/integrations
Click “Add Integration” and select “Webhook”
Configure your webhook endpoint:
- Name: A descriptive name for this webhook
- URL: Your HTTPS endpoint that will receive webhook payloads
- Custom Headers: Add custom headers for authentication (e.g., Authorization: Bearer your-secret-token)

Step 2: Create Notification Settings

After adding a webhook integration, configure which events trigger notifications:

Go to zeropath.com/app/settings/notifications
Click “Create Notification Setting”
Configure your notification preferences:
- Notification Channel: Select “Webhook” from the available channels
- Webhook: Choose from your list of webhook integrations
- Repositories: Select specific repositories or choose “All Repositories”
- Event Types: Select which events should trigger notifications
- Vulnerability Score Threshold: For vulnerability events, set the minimum threshold (Info, Low, Medium, High, or Critical)

The vulnerability score threshold only applies to vulnerability-related events like NEW_VULNERABILITIES_FULL_SCAN and NEW_VULNERABILITIES_PR. Other events like SCAN_COMPLETE will always be sent regardless of this setting.

ZeroPath supports multiple notification channels. When creating a notification setting, you’ll first select “Webhook” as your channel type, then choose from your configured webhook integrations. Other notification channels may include email, Slack, or other integrations.

Example Configuration

Here’s an example of a typical webhook configuration:

Create Webhook Integration

Add a webhook endpoint in Integrations:

Name: “Production Security Alerts”
URL: https://api.example.com/webhooks/zeropath
Custom Headers:
- Authorization: Bearer prod-webhook-token-123
- X-Environment: production

Configure Notifications

Create notification settings:

Notification Channel: “Webhook”
Webhook: “Production Security Alerts” (from your webhook list)
Repositories: “backend-api”, “frontend-app”
Events: NEW_VULNERABILITIES_FULL_SCAN, NEW_VULNERABILITIES_PR, PR_BLOCKED
Vulnerability Score Threshold: High

Result

You’ll receive webhooks only for:

New vulnerabilities with High or Critical scores in selected repos
Blocked PRs in selected repos
No notifications for vulnerabilities below High threshold

Repository Filtering

You can configure webhooks at different scopes:

Select “All Repositories” to receive notifications for events across your entire organization. New repositories are automatically included.

Vulnerability Score Filtering

The vulnerability score threshold helps reduce noise by filtering out lower-priority vulnerabilities. ZeroPath uses a 0-100 scoring system categorized into five levels:

Threshold Level	Score Range	Description	Typical Use Case
Critical	90-100	Immediate action required	Production systems, zero-tolerance environments
High	70-89	Serious issues requiring prompt attention	Important systems, should be addressed soon
Medium	40-69	Moderate risk vulnerabilities	Standard threshold for most projects
Low	10-39	Minor issues with limited impact	Development environments, code quality
Info	0-9	Informational findings	Audit trails, compliance tracking

When you select a threshold level (e.g., “High”), you’ll receive notifications for all vulnerabilities at that level and above. For example, selecting “High” will notify you of both High and Critical vulnerabilities.

Multiple Webhook Configurations

You can create multiple webhook integrations and notification settings to handle different scenarios. Each notification setting can use the “Webhook” channel with different webhook integrations:

Critical Alerts

Use Case: Immediate notifications for critical issues

Webhook: PagerDuty integration
Repositories: Production repos only
Events: NEW_VULNERABILITIES_FULL_SCAN, PR_BLOCKED
Vulnerability Score Threshold: Critical

Team Updates

Use Case: Daily team notifications

Webhook: Slack channel
Repositories: All repositories
Events: SCAN_COMPLETE, REPORT_COMPLETE
Vulnerability Score Threshold: Medium

Audit Trail

Use Case: Compliance logging

Webhook: SIEM system
Repositories: All repositories
Events: All event types
Vulnerability Score Threshold: Info (capture everything)

PR Workflow

Use Case: Developer notifications

Webhook: GitHub Actions
Repositories: Active development repos
Events: PR_SCAN_COMPLETE, NEW_VULNERABILITIES_PR
Vulnerability Score Threshold: High

Managing Notification Settings

You can create multiple notification settings using the same webhook integration with different configurations. This allows you to route different types of events or vulnerability score thresholds to the same endpoint but with different filtering rules.

To manage your webhook configurations:

View All Settings: Navigate to zeropath.com/app/settings/notifications to see all active configurations
Edit Settings: Click on any notification setting to modify repositories, events, or vulnerability score thresholds
Enable/Disable: Temporarily disable notifications without deleting the configuration
Test Webhooks: Use the “Test” button to send a sample payload to verify your endpoint is working

Webhook Security

Always use HTTPS endpoints for webhooks to ensure data is encrypted in transit.

Authentication with Custom Headers

ZeroPath allows you to add custom headers to webhook requests for authentication. This flexible approach lets you implement security that matches your infrastructure: Common Authentication Patterns:

// Example 1: Bearer Token
// Custom Header: Authorization: Bearer your-secret-token

app.post('/webhooks/zeropath', (req, res) => {
  const authHeader = req.headers['authorization'];
  if (authHeader !== 'Bearer your-secret-token') {
    return res.status(401).send('Unauthorized');
  }
  // Process webhook...
});

// Example 2: API Key
// Custom Header: X-API-Key: your-api-key

app.post('/webhooks/zeropath', (req, res) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.WEBHOOK_API_KEY) {
    return res.status(401).send('Invalid API key');
  }
  // Process webhook...
});

// Example 3: Custom Secret Header
// Custom Header: X-Webhook-Secret: your-webhook-secret

app.post('/webhooks/zeropath', (req, res) => {
  const secret = req.headers['x-webhook-secret'];
  if (secret !== process.env.ZEROPATH_WEBHOOK_SECRET) {
    return res.status(401).send('Invalid webhook secret');
  }
  // Process webhook...
});

You can add multiple custom headers for enhanced security, such as combining an API key with a timestamp for replay attack prevention.

Benefits of Custom Headers:

Flexibility: Use any authentication scheme that fits your infrastructure
Compatibility: Works with existing API gateways and authentication middleware
Multiple Headers: Add multiple headers for different purposes (auth, routing, metadata)
Standard Patterns: Use industry-standard authentication patterns like Bearer tokens

Best Practices

Implement Idempotency

Webhooks may be delivered more than once. Use the event ID to ensure you process each event only once.

Respond Quickly

Your endpoint should return a 2xx status code within 10 seconds. Process webhook data asynchronously if needed.

Handle Retries

ZeroPath will retry failed webhook deliveries with exponential backoff. Ensure your endpoint can handle duplicate events.

Monitor Webhook Health

Set up monitoring for your webhook endpoints to ensure they’re receiving and processing events correctly.

Use Webhook Filtering

Only subscribe to events you need to reduce noise and processing overhead.

Error Handling

ZeroPath uses the following retry policy for failed webhook deliveries:

Initial Retry: 30 seconds after first failure
Subsequent Retries: Exponential backoff (1min, 2min, 4min, 8min, 16min)
Max Retries: 6 attempts over ~30 minutes
Final Action: Webhook marked as failed and notification sent

Need Help?

Contact Support

Having issues with webhooks? Our support team is here to help.

For more detailed API information, check our API Reference or join our Discord community for help from other developers.

Overview

​Overview

Quick Setup

​How Webhooks Work

​Supported Event Types

SCAN_STARTED

SCAN_COMPLETE

SCAN_FAILED

SCAN_SCHEDULED

PR_SCAN_STARTED

PR_SCAN_COMPLETE

NEW_VULNERABILITIES_FULL_SCAN

NEW_VULNERABILITIES_PR

VULNERABILITY_PATCHED

VULNERABILITY_REOPENED

PR_BLOCKED

PR_MERGED_WITH_ISSUES

REPORT_COMPLETE

LONG_RUNNING_SCAN

AUDIT_LOG_EVENT

​Webhook Payload Structure

​Common Fields

​Event Payload Examples

​NEW_VULNERABILITIES_FULL_SCAN

​NEW_VULNERABILITIES_PR

​Configuring Webhooks

Integrations

Notifications

​Setting Up Webhooks

​Step 1: Add a Webhook Integration

​Step 2: Create Notification Settings

​Example Configuration

​Repository Filtering

​Vulnerability Score Filtering

​Multiple Webhook Configurations

Critical Alerts

Team Updates

Audit Trail

PR Workflow

​Managing Notification Settings

​Webhook Security

​Authentication with Custom Headers

​Best Practices

​Error Handling

​Need Help?

Contact Support

Overview

How Webhooks Work

Supported Event Types

Webhook Payload Structure

Common Fields

Event Payload Examples

NEW_VULNERABILITIES_FULL_SCAN

NEW_VULNERABILITIES_PR

Configuring Webhooks

Setting Up Webhooks

Step 1: Add a Webhook Integration

Step 2: Create Notification Settings

Example Configuration

Repository Filtering

Vulnerability Score Filtering

Multiple Webhook Configurations

Managing Notification Settings

Webhook Security

Authentication with Custom Headers

Best Practices

Error Handling

Need Help?