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 an alert triggers and the destination is a webhook, BreachSpider sends an HTTP POST request to your configured URL with a JSON payload containing the alert data.

Your endpoint receives the payload, processes it, and returns an HTTP 2xx response to acknowledge receipt. If your endpoint returns a non-2xx status or times out, BreachSpider retries the delivery (up to 3 attempts with exponential backoff).

Setting Up a Webhook

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

Name (required): A descriptive name (e.g., "SIEM Integration", "PagerDuty Webhook", "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 using this secret. 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": "kev.new",
  "timestamp": "2026-06-07T12:00:00Z",
  "environment": {
    "id": 5,
    "name": "Water Treatment Plant Alpha"
  },
  "finding": {
    "cve_id": "CVE-2025-32433",
    "bsid": "BS-2025-254014-C",
    "severity": "CRITICAL",
    "cvss": 10.0,
    "bcs": 9.8,
    "epss": 0.97,
    "epss_percentile": 0.99,
    "kev_flagged": true,
    "exploit_maturity": "WEAPONIZED",
    "asset_name": "SCADA Workstation 01",
    "asset_type": "Engineering Workstation",
    "layer": "OS",
    "match_confidence": "HIGH",
    "patch_status": "patched",
    "patch_version": "OTP-27.3.3"
  },
  "sage_summary": "Critical pre-authentication remote code execution in Erlang/OTP SSH. Affects any system running Erlang SSH daemon.",
  "detail_url": "https://breachspider.com/cves/CVE-2025-32433"
}

Webhook Headers

Each webhook request includes:

Verifying Webhook Signatures

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

import hmac
import hashlib

def verify_signature(payload_body, secret, signature_header):
    expected = hmac.new(
        secret.encode('utf-8'),
        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.

PagerDuty (webhook): PagerDuty's Events API v2 accepts webhook payloads. Point a BreachSpider webhook at your PagerDuty service endpoint to trigger incidents.

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: Ensure you are using the correct secret and comparing the full sha256= prefix.

Duplicate deliveries: Use the X-BreachSpider-Delivery header for idempotency. If you receive two requests with the same delivery ID, process only the first.