Webhooks & SIEM Integration¶

Delivers real-time notifications to external systems when events occur during an engagement. Supports Slack, Microsoft Teams, Splunk, generic JSON, CEF, and syslog formats.

Event types¶

Event	Fires when
`finding_added`	A new finding is discovered
`finding_verified`	A finding is verified with a working PoC
`phase_changed`	A testing phase starts or completes
`engagement_completed`	The full engagement finishes
`engagement_signed`	Client signs the authorization
`critical_finding`	A finding with Critical severity is added
`retest_completed`	A retest cycle (`/retest`) completes
`report_ready`	A report is generated and available for download
`surface_changed`	Surface Drift Detection detects a change
`monitor_alert`	Continuous Monitoring triggers an alert
`*`	All events (wildcard)

Supported formats¶

Format	Description	Typical destination
`json`	Generic JSON payload	Any HTTP endpoint
`slack`	Slack Block Kit message	Slack incoming webhook
`teams`	Adaptive Card	Microsoft Teams connector
`cef`	Common Event Format	ArcSight, QRadar
`syslog`	RFC 5424 syslog	Splunk HEC, rsyslog

API endpoints¶

List webhooks¶

GET /api/v1/webhooks

Returns all configured webhooks, ordered by creation date (newest first).

Create webhook¶

POST /api/v1/webhooks

{
  "name": "Slack - Critical Findings",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "secret": "optional-hmac-secret",
  "event_types": ["critical_finding", "engagement_completed"],
  "format": "slack",
  "retry_count": 3,
  "timeout_ms": 5000
}

Field	Type	Default	Description
`name`	string	required	Display name
`url`	string	required	Destination URL
`secret`	string	null	HMAC-SHA256 signing secret. If set, each delivery includes an `X-Webhook-Signature` header
`event_types`	list	`["finding_added", "phase_changed", "engagement_completed"]`	Which events trigger this webhook
`format`	string	`json`	Output format: `json`, `slack`, `teams`, `cef`, `syslog`
`retry_count`	int	`3`	Number of retries on failure (0-10)
`timeout_ms`	int	`5000`	Request timeout in milliseconds (1000-30000)

Get / Update / Delete webhook¶

GET    /api/v1/webhooks/{webhook_id}
PUT    /api/v1/webhooks/{webhook_id}
DELETE /api/v1/webhooks/{webhook_id}

Update accepts partial payloads -- only include fields you want to change. Re-enabling a webhook (is_active: true) resets the failure counter.

Test webhook¶

POST /api/v1/webhooks/{webhook_id}/test

{
  "event_type": "test",
  "payload": {"message": "Hello from BeDefended"}
}

Sends a test delivery to verify connectivity. The delivery is logged in the delivery history.

Delivery history¶

GET /api/v1/webhooks/{webhook_id}/deliveries?limit=50

Returns recent delivery attempts with status code, success flag, attempt number, and any error message.

List available event types¶

GET /api/v1/webhooks/events/types

Returns all event types with descriptions.

Circuit breaker¶

Webhooks have a built-in failure counter. After repeated delivery failures, the webhook is automatically deactivated (is_active: false). Re-enabling it via PUT resets the counter to zero.

Access control¶

Webhook management is admin-only. Misconfigured webhooks can leak sensitive finding data to external systems. Pentesters can see that webhooks exist but cannot create, modify, or delete them.

Connections to other features¶

Surface Drift: when a surface change is detected, a surface_changed event fires
Continuous Monitoring: when a monitoring schedule detects a regression, a monitor_alert event fires
Compliance Mapping: report generation triggers report_ready, which can notify stakeholders that a compliance gap report is ready