Webhooks

Custom webhooks allow BreachSpider to send alert data to any HTTP endpoint. Use webhooks to integrate with tools that are not natively supported, build custom automation, or feed alert data into your security orchestration platform.

Available on Standard tier and above.

How Webhooks Work

When the alert engine sends an alert, every active webhook in your organization receives an HTTP POST with a JSON payload. See Alerts Overview for which CVEs are alerted.

Your endpoint should return an HTTP 2xx response. BreachSpider waits up to 10 seconds for a 2xx response. Failed deliveries are not retried: the alert is recorded as failed and is not sent again. After 5 failed deliveries the webhook is disabled; re-enable it from the dashboard or with POST /api/v1/webhooks/{id}/enable.

Setting Up a Webhook

1. Navigate to Integrations > Connections > Add Connection.
2. Select Webhook as the connection type.
3. Fill in the configuration:

Label (required): A descriptive name (e.g., "SIEM Integration", "Custom Dashboard").

URL (required): The HTTP endpoint that will receive the webhook payload. Must be HTTPS for production use.

Secret (auto-generated): A shared secret used to sign webhook payloads. BreachSpider includes an X-BreachSpider-Signature header with each request, containing an HMAC-SHA256 signature of the payload. The HMAC key is the SHA-256 hex digest of this secret (see the verification example below). Verify the signature on your endpoint to confirm the payload came from BreachSpider.

1. Click Test Connection to send a test payload to your endpoint.
2. Verify your endpoint received and processed the test payload.
3. Click Save.

Webhook Payload Format

{
  "event": "cve.alert",
  "version": "1.0",
  "timestamp": "2026-09-28T02:15:03.412000+00:00",
  "data": {
    "cve_id": "CVE-2025-32433",
    "title": "Erlang/OTP SSH pre-authentication remote code execution",
    "cvss_score": 10.0,
    "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
    "patch_status": "patched",
    "kev_flagged": true,
    "epss_score": 0.97,
    "sage_priority": "PATCH NOW",
    "published_at": "2025-04-16T22:15:14+00:00",
    "url": "https://breachspider.com/ics-cve/CVE-2025-32433",
    "executive_summary": "AI-generated summary of the vulnerability.",
    "mitigation": "AI-generated mitigation guidance.",
    "causal_boundary": "AI-generated scope note.",
    "virtual_patch": "AI-drafted detection rule, or null. Review before deploying.",
    "watchlist_match": {
      "entity_type": "environment",
      "entity_name": "SCADA Workstation 01 in Water Treatment Plant Alpha"
    }
  }
}

event is always cve.alert. sage_priority is one of PATCH NOW, PATCH NEXT, MONITOR, IGNORE. watchlist_match.entity_type is vendor or product for watchlist matches and environment for asset matches. The AI fields can be null.

Webhook Headers

Each webhook request includes:

Discord webhook URLs receive a Discord-formatted embed instead, without the signature headers.

Verifying Webhook Signatures

Always verify the X-BreachSpider-Signature header to ensure the payload came from BreachSpider and was not tampered with:

import hashlib
import hmac

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    # BreachSpider signs with the SHA-256 hex digest of your webhook secret as the HMAC key.
    key = hashlib.sha256(secret.encode("utf-8")).hexdigest().encode("utf-8")
    expected = hmac.new(key, payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Webhook Secret Rotation

To rotate the webhook secret:

curl -X POST \
  -H "Authorization: Bearer bs_live_..." \
  "https://breachspider.com/api/v1/webhooks/42/rotate-secret"

A new secret is generated. Update your endpoint to use the new secret. The old secret is invalidated immediately.

Use Cases

SIEM integration: Forward BreachSpider alerts to Splunk, QRadar, or Elastic via webhook. Your SIEM can correlate vulnerability intelligence with network telemetry.

Custom dashboard: Build an internal dashboard that aggregates BreachSpider alerts with other security feeds. Your webhook endpoint stores alerts in a database and your dashboard queries it.

ChatOps bot: Forward alerts to a custom Slack or Teams bot that provides additional context or automated response options.

Ticketing systems: For ticketing systems not natively supported (e.g., Zendesk, Freshservice), use webhooks to create tickets via their API.

Troubleshooting

Webhook not delivering: Check that your endpoint is reachable from the internet (BreachSpider servers must be able to reach your URL). Verify the URL is correct and uses HTTPS.

Signature verification failing: The HMAC key is the SHA-256 hex digest of your secret, not the secret itself. Compare the full value including the sha256= prefix.

Duplicate deliveries: Each CVE is sent at most once per webhook. Use data.cve_id if your receiver needs to de-duplicate.