Reference: Integration Events#

This page documents all events that SilentBolt can dispatch to configured integrations.

---

Event Catalog#

Event	Trigger Point	Payload Summary
scan.completed	Scan finishes with status done	Scan ID, domain name, completion time, finding counts by severity, report availability
finding.created	A critical or high-severity finding is detected during post-processing	Finding ID, title, severity, matched URL/host, domain name, scan ID
finding.escalated	A finding's severity or status escalates (e.g., drift detection marks it as a regression)	Finding ID, title, old severity/status, new severity/status, domain name

---

Event Payload Structure#

All events share a common envelope:

{
  "event_type": "scan.completed",
  "timestamp": "2025-03-09T22:00:00Z",
  "company_id": "uuid",
  "data": {
    // Event-specific fields
  }
}

scan.completed Data#

{
  "scan_id": "uuid",
  "domain": "example.com",
  "status": "done",
  "started_at": "2025-03-09T21:30:00Z",
  "completed_at": "2025-03-09T22:00:00Z",
  "duration_seconds": 1800,
  "findings": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "low": 8,
    "info": 15,
    "total": 42
  },
  "hosts_count": 8,
  "endpoints_count": 156,
  "new_findings": 7,
  "drift_summary": {
    "new": 7,
    "changed": 2,
    "resolved": 3,
    "regression": 1
  }
}

finding.created Data#

{
  "finding_id": "uuid",
  "scan_id": "uuid",
  "domain": "example.com",
  "title": "SQL Injection in login endpoint",
  "severity": "critical",
  "risk_score": 95,
  "matched_url": "https://example.com/api/login",
  "matched_host": "example.com",
  "matched_port": 443,
  "template_id": "template:sqli-login",
  "change_type": "new"
}

finding.escalated Data#

{
  "finding_id": "uuid",
  "scan_id": "uuid",
  "domain": "example.com",
  "title": "Open redirect on OAuth callback",
  "previous_severity": "medium",
  "current_severity": "high",
  "previous_status": "resolved",
  "current_status": "reopened",
  "change_type": "regression"
}

---

Event Dispatch Behavior#

Timing#

• scan.completed is dispatched once, immediately after report generation completes.
• finding.created events are dispatched for each critical or high finding during post-processing. For a scan with 10 critical/high findings, 10 events are dispatched.
• finding.escalated events are dispatched when drift detection identifies regressions or severity changes.

Delivery#

• Events are dispatched to all active integrations configured for the company.
• Each integration receives the event independently — a failure to deliver to one integration does not block others.

Retry#

• If delivery fails (HTTP error, timeout, etc.), SilentBolt retries the dispatch.
• Retry behavior is tracked in dispatch_logs with status and error details.

Dispatch Logging#

Every dispatch attempt is recorded:

Field	Description
Event type	The event that triggered the dispatch
Integration ID	The target integration
Status	success, failed, retrying
HTTP status code	Response from the external service
Error message	Error details (if failed)
Timestamp	When the dispatch occurred

---

Provider-Specific Formatting#

Each integration provider receives events formatted for its specific API:

Provider	Format
Microsoft Teams	Adaptive Card via Incoming Webhook
Telegram	Markdown-formatted message via Bot API
GitHub	Issue creation in the configured repository
Jira	Issue creation in the configured project

Microsoft Teams Example#

Events are sent as an Adaptive Card with:

• Color-coded header matching severity (red for critical, orange for high).
• Finding title and domain.
• Key metrics (for scan.completed).
• Link back to SilentBolt UI.

Telegram Example#

Events are sent as a formatted message with:

• Emoji indicators for severity (🔴 critical, 🟠 high).
• Finding or scan summary.
• Link to the SilentBolt UI.

GitHub Example#

finding.created events create a GitHub Issue with:

• Issue title: [SilentBolt] {severity}: {finding_title}
• Issue body: finding details, matched URL, evidence summary, link to SilentBolt.
• Labels: severity level (if label exists in the repository).

Jira Example#

finding.created events create a Jira Issue with:

• Summary: [SilentBolt] {finding_title}
• Description: finding details, evidence, remediation guidance.
• Priority: mapped from SilentBolt severity.
• Link back to SilentBolt.

---

Related Pages#

• Integrations
• Scans
• Findings
• Statuses and Severities