> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Receive real-time notifications about security events in your repositories
## 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.
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:
When a full repository scan begins
When a full repository scan finishes successfully
When a scan fails to complete
When a scan is scheduled
When a pull request scan begins
When a pull request scan completes
When new vulnerabilities are detected in a full repository scan
When new vulnerabilities are detected in a pull request
When a vulnerability is fixed. If a single pull request patches multiple vulnerabilities, a separate event is sent for each one.
When a vulnerability reappears
When a pull request is blocked due to vulnerabilities
When a pull request is merged to main branch with open vulnerabilities
When a report is generated
When a scan is taking unusually long
Important audit log events
When a new CVE is detected in a project dependency
When a new dependency vulnerability issue is created from any SCA source
When an external system sends an event to a ZeroPath inbound webhook trigger
When a patch pull request is denied or rejected
When a vulnerability's status changes (e.g., from pending review to accepted risk). Fired for all triage actions including archive, unarchive, mark as true positive, mark as false positive, resolve, and unresolve — whether performed from the dashboard, the API, or the ZeroPath AI agent.
When a dependency (SCA) scan begins
When a dependency (SCA) scan finishes successfully
When a dependency (SCA) scan fails to complete
When a new repository is added to the organization
## Webhook Payload Structure
All webhook payloads follow a consistent structure with event-specific data:
### Common Fields
| Field | Type | Required | Description |
| ------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time` | integer | Yes | Unix epoch seconds when the event was emitted |
| `host` | string | Yes | Origin host (e.g., `zeropath.com`) |
| `source` | string | Yes | Source system identifier |
| `sourcetype` | enum | Yes | Event type. One of `SCAN_STARTED`, `SCAN_COMPLETE`, `PR_SCAN_STARTED`, `PR_SCAN_COMPLETE`, `NEW_VULNERABILITIES_PR`, `NEW_VULNERABILITIES_FULL_SCAN`, `VULNERABILITY_PATCHED`, `VULNERABILITY_REOPENED`, `AUDIT_LOG_EVENT`, `SCAN_FAILED`, `SCAN_SCHEDULED`, `LONG_RUNNING_SCAN`, `PR_BLOCKED`, `PR_MERGED_WITH_ISSUES`, `REPORT_COMPLETE`, `SCA_NEW_CVE`, `SCA_NEW_ISSUE`, `INBOUND_WEBHOOK`, `PATCH_PR_DENIED`, `VULNERABILITY_STATUS_CHANGED`, `SCA_SCAN_COMPLETE`, `SCA_SCAN_STARTED`, `SCA_SCAN_FAILED`, `REPO_ADDED` |
| `event` | object | Yes | Event payload object containing details |
### `event` object
| Field | Type | Required | Description |
| ---------------------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------ |
| `timestamp` | string (date-time) | Yes | ISO 8601 timestamp of the event |
| `organization` | object | Yes | Organization details |
| `organization.id` | string | Yes | Organization ID |
| `organization.name` | string | No | Organization name |
| `repository` | object | No | Repository details |
| `repository.id` | string | Yes | Repository ID |
| `repository.name` | string | Yes | Repository name |
| `scan` | object | No | Scan details for scan-related events |
| `scan.id` | string | Yes | Scan ID |
| `scan.type` | string | Yes | Scan type (e.g., `FullScan`, `PrScan`) |
| `scan.status` | string | Yes | One of `started`, `completed`, `failed`, `scheduled`, `blocked`, `merged_with_issues`, `unknown` |
| `scan.duration_minutes` | integer | No | Scan duration in minutes |
| `scan.vulnerability_summary.total` | integer | Yes | Total vulnerabilities (when present) |
| `scan.vulnerability_summary.by_severity` | object | Yes | Counts for `critical`, `high`, `medium`, `low`, `info` |
| `scan.url` | string | Yes | Link to view the scan in ZeroPath |
| `audit_log` | object | No | Present for `AUDIT_LOG_EVENT` |
| `audit_log.id` | string | Yes | Audit log ID |
| `audit_log.endpoint` | string | Yes | API endpoint called |
| `audit_log.arguments` | object | No | Arguments passed to the endpoint |
| `audit_log.caller` | object | No | Caller info (`id`, `email`) |
| `audit_log.timestamp` | string (date-time) | Yes | When the audit event occurred |
| `error` | string | No | Error message (present in failure events) |
| `metadata` | object | No | Additional event-specific data |
| `vulnerability` | object | No | Detailed vulnerability information |
### 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. When a single pull request patches multiple vulnerabilities, you will receive one `VULNERABILITY_PATCHED` event per vulnerability.
* `REPORT_COMPLETE`: `event.metadata.reportId` required
## Event Payload Examples
```json SCAN_COMPLETE theme={null}
{
"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"
}
}
}
```
```json SCAN_FAILED theme={null}
{
"time": 1729101200,
"host": "zeropath.com",
"source": "zeropath",
"sourcetype": "SCAN_FAILED",
"event": {
"timestamp": "2025-10-16T12:40:00Z",
"organization": { "id": "org_123", "name": "Acme Corp" },
"repository": { "id": "repo_123", "name": "backend-api" },
"scan": { "id": "scan_def", "type": "FullScan", "status": "failed", "url": "https://zeropath.com/scans/scan_def" },
"error": "Timeout contacting build server"
}
}
```
```json NEW_VULNERABILITIES_FULL_SCAN theme={null}
{
"time": 1729101500,
"host": "zeropath.com",
"source": "zeropath",
"sourcetype": "NEW_VULNERABILITIES_FULL_SCAN",
"event": {
"timestamp": "2025-10-16T12:45:00Z",
"organization": { "id": "org_123", "name": "Acme Corp" },
"repository": { "id": "repo_123", "name": "backend-api" },
"vulnerability": {
"id": "vuln_001",
"generatedTitle": "SQL Injection risk",
"severity": 8.2
}
}
}
```
```json PR_BLOCKED theme={null}
{
"time": 1729101800,
"host": "zeropath.com",
"source": "zeropath",
"sourcetype": "PR_BLOCKED",
"event": {
"timestamp": "2025-10-16T12:50:00Z",
"organization": { "id": "org_123", "name": "Acme Corp" },
"repository": { "id": "repo_123", "name": "backend-api" },
"metadata": { "prId": "01HXYZ", "prNumber": 123 }
}
}
```
## Configuring Webhooks
Add and manage webhook endpoints
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
1. Navigate to [zeropath.com/app/settings/integrations](https://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
After adding a webhook integration, configure which events trigger notifications:
1. Go to [zeropath.com/app/settings/notifications](https://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)
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:
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`
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
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.
Choose individual repositories to limit notifications to specific projects. This is useful for:
* Different vulnerability score thresholds per project
* Routing alerts to different teams
* Focusing on critical repositories
### 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:
**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
**Use Case**: Daily team notifications
* Webhook: Slack channel
* Repositories: All repositories
* Events: `SCAN_COMPLETE`, `REPORT_COMPLETE`
* Vulnerability Score Threshold: Medium
**Use Case**: Compliance logging
* Webhook: SIEM system
* Repositories: All repositories
* Events: All event types
* Vulnerability Score Threshold: Info (capture everything)
**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:
1. **View All Settings**: Navigate to [zeropath.com/app/settings/notifications](https://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
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:**
```javascript theme={null}
// 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
## Inbound Webhooks (Agent Triggers)
In addition to the outbound notification webhooks described above, ZeroPath supports **inbound webhooks** that trigger automated agent actions. Inbound webhooks allow external systems to send events to ZeroPath and have the AI agent respond based on a configurable prompt.
### How Inbound Webhooks Work
1. You create an event trigger with the `INBOUND_WEBHOOK` event type via the API or MCP server.
2. ZeroPath generates a unique webhook URL and secret for the trigger:
```
https://zeropath.com/api/agent/webhook/{triggerId}?secret={webhookSecret}
```
3. When an external system sends an HTTP POST to this URL, the agent executes the trigger's prompt with the webhook payload available as context.
4. You can view trigger execution history and results through the API.
### Use Cases
* **External CI/CD integration**: Trigger the agent to triage findings when your build pipeline completes.
* **Third-party tool integration**: Have external security tools send findings to the agent for automated analysis.
* **Custom automation**: Connect any system that can send HTTP POST requests to trigger agent workflows.
Inbound webhooks are managed through the Agent API endpoints. Each inbound webhook trigger includes an auto-generated secret for authentication. You can list, create, update, and delete triggers using the V2 API or the MCP server.
## Best Practices
Webhooks may be delivered more than once. Use the event ID to ensure you process each event only once.
Your endpoint should return a 2xx status code within 10 seconds. Process webhook data asynchronously if needed.
ZeroPath will retry failed webhook deliveries with exponential backoff. Ensure your endpoint can handle duplicate events.
Set up monitoring for your webhook endpoints to ensure they're receiving and processing events correctly.
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?
Having issues with webhooks? Our support team is here to help.
For more detailed API information, check our [API Reference](/api-reference/introduction) or join our [Discord community](https://discord.gg/ZRqDvZ6qjJ) for help from other developers.