Webhooks

​

Overview

​

How Webhooks Work

• 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

​

Webhook Payload Structure

​

Common Fields

​

event object

​

Event-specific requirements

• SCAN_STARTED: event.scan required
• PR_SCAN_STARTED: event.scan required
• SCAN_COMPLETE: event.scan required
• PR_SCAN_COMPLETE: event.scan required
• SCAN_FAILED: event.scan and event.error required
• NEW_VULNERABILITIES_PR: either event.vulnerability or event.scan required
• NEW_VULNERABILITIES_FULL_SCAN: either event.vulnerability or event.scan required
• LONG_RUNNING_SCAN: event.metadata.runningMinutes required
• AUDIT_LOG_EVENT: event.audit_log required
• SCAN_SCHEDULED: event.metadata with scheduleId, crontab, isEnabled, action required
• PR_BLOCKED: event.metadata.prId and event.metadata.prNumber required
• PR_MERGED_WITH_ISSUES: event.metadata.prUrl and event.metadata.targetBranch required
• VULNERABILITY_REOPENED/VULNERABILITY_PATCHED: either event.metadata or event.vulnerability required
• REPORT_COMPLETE: event.metadata.reportId required

​

Event Payload Examples

{
  "time": 1729101000,
  "host": "zeropath.com",
  "source": "zeropath",
  "sourcetype": "SCAN_COMPLETE",
  "event": {
    "timestamp": "2025-10-16T12:34:56Z",
    "organization": { "id": "org_123", "name": "Acme Corp" },
    "repository": { "id": "repo_123", "name": "backend-api" },
    "scan": {
      "id": "scan_abc",
      "type": "FullScan",
      "status": "completed",
      "duration_minutes": 8,
      "vulnerability_summary": {
        "total": 3,
        "by_severity": { "critical": 0, "high": 1, "medium": 1, "low": 1, "info": 0 }
      },
      "url": "https://zeropath.com/scans/scan_abc"
    }
  }
}

​

Configuring Webhooks

​

Setting Up Webhooks

​

Step 1: Add a Webhook Integration

1. Navigate to zeropath.com/app/settings/integrations
2. Click “Add Integration” and select “Webhook”
3. 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

1. Go to zeropath.com/app/settings/notifications
2. Click “Create Notification Setting”
3. 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)

​

Example Configuration

​

Repository Filtering

​

Vulnerability Score Filtering

​

Multiple Webhook Configurations

​

Managing Notification Settings

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

​

Webhook Security

​

Authentication with Custom Headers

// 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...
});

• 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

​

Error Handling

• 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?