Integrations Guide

ThreatWeaver supports outbound integrations with ticketing systems, messaging platforms, and custom webhooks. All integration routes are gated behind the connectors license module and require the MANAGE_SETTINGS permission.

Supported Integration Types

Integration	Type	Use Case
Jira	Ticketing	Create and track remediation tickets from vulnerability findings
ServiceNow	Ticketing	Incident and change management for vulnerability remediation
Slack	Messaging	Real-time notifications for new findings, scan completions, and SLA breaches
Microsoft Teams	Messaging	Team channel notifications for security events
PagerDuty	Alerting	On-call escalation for critical vulnerability discoveries
Email (SMTP)	Messaging	Email notifications for scan results and scheduled reports
Custom Webhooks	Generic	HTTP POST callbacks to any endpoint for custom automation

Architecture

Webhook System

Event Types

The webhook system supports subscribing to these event categories:

• Finding events -- New finding created, finding status changed, finding resolved
• Scan events -- Scan started, scan completed, scan failed
• SLA events -- SLA breach warning, SLA breach confirmed
• Sync events -- Tenable sync completed, sync failed
• Assessment events -- AppSec assessment completed, new critical finding

Creating a Webhook

API: POST /api/integrations/webhooks

Required fields:

• name -- Display name for the webhook
• url -- Target URL that will receive HTTP POST requests
• events -- Array of event types to subscribe to

Optional fields:

• secret -- Shared secret for HMAC signature verification (recommended)
• headers -- Custom HTTP headers to include with each delivery
• retryCount -- Number of retry attempts for failed deliveries (default: 3)

Webhook Payload

Each delivery is an HTTP POST with:

• JSON body containing the event type, timestamp, and event-specific data
• X-TW-Signature header with HMAC-SHA256 signature (if secret is configured)
• X-TW-Event header with the event type
• Custom headers if configured

Delivery Tracking

Every webhook delivery is logged with:

• HTTP status code of the response
• Response time
• Success or failure status
• Error message if failed

Delivery logs are viewable at /admin/integrations and via the GET /api/integrations/webhooks/deliveries endpoint.

Retry Logic

Failed deliveries are automatically retried with exponential backoff:

• Retry 1: 30 seconds after failure
• Retry 2: 2 minutes after first retry
• Retry 3: 10 minutes after second retry

Manual retry is also available via POST /api/integrations/webhooks/deliveries/{id}/retry.

---

Jira Integration Setup

Step 1: Configure Connection

Navigate to Admin > Integrations and select Jira.

Provide:

• Jira URL -- Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
• Email -- Jira account email for API authentication
• API Token -- Generated from Atlassian account settings (Account > Security > API tokens)

Step 2: Configure Project Mapping

Map ThreatWeaver severity levels to Jira issue types and priorities:

ThreatWeaver Severity	Jira Issue Type	Jira Priority
Critical	Bug	Highest
High	Bug	High
Medium	Task	Medium
Low	Task	Low

Step 3: Configure Field Mapping

Map ThreatWeaver finding fields to Jira issue fields:

• Summary -- Vulnerability title and affected asset
• Description -- Full finding details with evidence, remediation guidance, and compliance references
• Labels -- Severity, vulnerability type, affected module
• Components -- Affected system component (if configured)

Step 4: Test Connection

Use the Test Connection button to verify API credentials and project access. The test creates and immediately deletes a test issue to confirm write permissions.

Step 5: Enable Auto-Creation

Optionally enable automatic ticket creation for findings above a configurable severity threshold.

---

API Reference

Method	Path	Description
GET	/api/integrations/webhooks	List all webhooks with available events
POST	/api/integrations/webhooks	Create a new webhook subscription
GET	/api/integrations/webhooks/:id	Get webhook details
PUT	/api/integrations/webhooks/:id	Update webhook configuration
DELETE	/api/integrations/webhooks/:id	Delete a webhook
GET	/api/integrations/webhooks/deliveries	List delivery logs
POST	/api/integrations/webhooks/deliveries/:id/retry	Retry a failed delivery
GET	/api/integrations/docs/openapi	OpenAPI specification

Security Considerations

• All webhook URLs are validated before creation to prevent SSRF
• User-supplied text fields (names, etc.) are sanitized via stripHtmlTags to prevent stored XSS
• API tokens and secrets are encrypted at rest
• Webhook secrets enable HMAC signature verification for payload authenticity

Related Pages

• Admin Overview -- Admin module overview