Skip to content

Webhooks Integration Guide

Webhooks deliver real-time event notifications to any HTTP endpoint you control. Use webhooks to build custom alert pipelines, trigger automation, or feed your SIEM.

Creating a Webhook

curl -X POST \
  -H "Authorization: Bearer bs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SOC Alert Pipeline",
    "url": "https://your-server.com/breachspider-webhook",
    "events": ["kev.new", "cve.critical", "exploit.confirmed"],
    "secret": "your-signing-secret"
  }' \
  "https://breachspider.com/api/v1/webhooks"

Event Types

Event Description
kev.new New KEV entry matching your assets
cve.critical New critical CVE (CVSS 9+) matching your assets
cve.high New high severity CVE matching your assets
exploit.confirmed Public exploit released for a CVE in your environment
asset.matched New CVE matched to one of your assets
report.ready Generated report is ready
ticket.created New ticket opened

Webhook Payload

{
  "event": "kev.new",
  "timestamp": "2026-06-07T13:34:43Z",
  "request_id": "bs-req-abc123",
  "data": {
    "cve_id": "CVE-2025-32433",
    "bsid": "BS-2025-254014-C",
    "severity": "CRITICAL",
    "cvss_score": 10.0,
    "bcs_score": 10.0,
    "kev_flagged": true,
    "exploit_maturity": "POC",
    "primary_vendor": "Erlang",
    "primary_product": "Erlang/OTP",
    "affected_assets": [
      {
        "asset_id": 42,
        "asset_name": "SCADA Middleware Server",
        "environment_id": 5,
        "environment_name": "Water Treatment Plant Alpha"
      }
    ],
    "patch_available": true,
    "breachspider_url": "https://breachspider.com/ics-cve/CVE-2025-32433"
  }
}

Verifying Signatures

Every webhook delivery includes an X-BreachSpider-Signature header. Verify it to confirm the request came from BreachSpider.

import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Policy

Failed deliveries are retried with exponential backoff:

  • Attempt 1: immediate
  • Attempt 2: 5 minutes
  • Attempt 3: 30 minutes
  • Attempt 4: 2 hours
  • Attempt 5: 8 hours

After 5 failed attempts the webhook is disabled. Re-enable via the dashboard or POST /api/v1/webhooks/{id}/enable.