Webhooks API

Erhalten Sie Echtzeit-Benachrichtigungen für CyberOrigen-Ereignisse.

Professional und Enterprise

Webhooks sind in den Professional und Enterprise Tarifen verfügbar.

Übersicht

Webhooks ermöglichen es Ihnen, HTTP-Callbacks zu empfangen, wenn Ereignisse in CyberOrigen auftreten. Konfigurieren Sie Endpunkte, um Benachrichtigungen über Scans, Findings, Compliance-Änderungen und mehr zu erhalten.

Endpunkte

Method	Endpoint	Beschreibung
GET	/api/v1/webhooks	Webhooks auflisten
POST	/api/v1/webhooks	Webhook erstellen
GET	/api/v1/webhooks/{id}	Webhook-Details abrufen
PATCH	/api/v1/webhooks/{id}	Webhook aktualisieren
DELETE	/api/v1/webhooks/{id}	Webhook löschen
POST	/api/v1/webhooks/{id}/test	Test-Ereignis senden
GET	/api/v1/webhooks/{id}/deliveries	Zustellungsverlauf auflisten

Webhook erstellen

POST /api/v1/webhooks
Content-Type: application/json

{
  "name": "Security Alerts",
  "url": "https://your-server.com/webhooks/cyberorigen",
  "events": [
    "scan.completed",
    "vulnerability.critical",
    "vulnerability.high"
  ],
  "secret": "your-webhook-secret",
  "active": true
}

Parameter

Feld	Typ	Erforderlich	Beschreibung
name	string	Ja	Beschreibender Name
url	string	Ja	HTTPS-Endpunkt-URL
events	array	Ja	Zu abonnierende Ereignisse
secret	string	Nein	Signatur-Secret zur Verifizierung
active	boolean	Nein	Webhook aktivieren/deaktivieren

Antwort

{
  "id": "webhook_abc123",
  "name": "Security Alerts",
  "url": "https://your-server.com/webhooks/cyberorigen",
  "events": ["scan.completed", "vulnerability.critical", "vulnerability.high"],
  "active": true,
  "created_at": "2025-12-21T10:00:00Z"
}

Verfügbare Ereignisse

Scan-Ereignisse

Ereignis	Beschreibung
scan.created	Neuer Scan initiiert
scan.started	Scan-Ausführung gestartet
scan.progress	Scan-Phase abgeschlossen
scan.completed	Scan erfolgreich beendet
scan.failed	Scan mit Fehler fehlgeschlagen

Schwachstellen-Ereignisse

Ereignis	Beschreibung
vulnerability.found	Neue Schwachstelle entdeckt
vulnerability.critical	Finding mit kritischem Schweregrad
vulnerability.high	Finding mit hohem Schweregrad
vulnerability.status_changed	Finding-Status aktualisiert
vulnerability.resolved	Finding als behoben markiert

Compliance-Ereignisse

Ereignis	Beschreibung
control.status_changed	Control-Status aktualisiert
evidence.uploaded	Neuer Nachweis hinzugefügt
evidence.expiring	Nachweis läuft bald ab
framework.score_changed	Compliance-Score geändert
audit.request_created	Neue Auditor-Anfrage

Sicherheits-Ereignisse

Ereignis	Beschreibung
quarantine.threat_detected	Malware im Upload erkannt
user.login_failed	Fehlgeschlagener Login-Versuch
user.mfa_disabled	MFA auf Account deaktiviert

Webhook-Payload

Alle Webhook-Zustellungen enthalten:

{
  "id": "delivery_xyz789",
  "event": "scan.completed",
  "timestamp": "2025-12-21T15:30:00Z",
  "data": {
    // Ereignisspezifische Daten
  }
}

Beispiel: Scan abgeschlossen

{
  "id": "delivery_xyz789",
  "event": "scan.completed",
  "timestamp": "2025-12-21T15:30:00Z",
  "data": {
    "scan_id": "scan_abc123",
    "target": "example.com",
    "status": "completed",
    "duration_seconds": 2700,
    "findings": {
      "total": 12,
      "critical": 1,
      "high": 3,
      "medium": 5,
      "low": 3
    }
  }
}

Beispiel: Kritische Schwachstelle

{
  "id": "delivery_abc456",
  "event": "vulnerability.critical",
  "timestamp": "2025-12-21T15:35:00Z",
  "data": {
    "finding_id": "finding_xyz789",
    "title": "Remote Code Execution",
    "severity": "critical",
    "cvss_score": 9.8,
    "target": "example.com",
    "affected_component": "https://example.com/api/upload",
    "cve_ids": ["CVE-2024-1234"],
    "scan_id": "scan_abc123"
  }
}

Signatur-Verifizierung

Wenn Sie ein secret angeben, signiert CyberOrigen jede Zustellung mit HMAC-SHA256.

Headers

X-CyberOrigen-Signature: sha256=abc123...
X-CyberOrigen-Event: scan.completed
X-CyberOrigen-Delivery: delivery_xyz789

Verifizierungs-Beispiel (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhooks/cyberorigen', (req, res) => {
  const signature = req.headers['x-cyberorigen-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

Verifizierungs-Beispiel (Python)

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask route
@app.route('/webhooks/cyberorigen', methods=['POST'])
def webhook():
    signature = request.headers.get('X-CyberOrigen-Signature')

    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    # Process webhook...
    return 'OK', 200

Webhook testen

Ein Test-Ereignis senden, um Ihren Endpunkt zu verifizieren:

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

Antwort

{
  "delivery_id": "delivery_test123",
  "status": "success",
  "response_code": 200,
  "response_time_ms": 145
}

Zustellungsverlauf

Webhook-Zustellungsversuche anzeigen:

GET /api/v1/webhooks/{webhook_id}/deliveries

Antwort

{
  "items": [
    {
      "id": "delivery_xyz789",
      "event": "scan.completed",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 145,
      "attempts": 1,
      "created_at": "2025-12-21T15:30:00Z",
      "delivered_at": "2025-12-21T15:30:00Z"
    },
    {
      "id": "delivery_abc456",
      "event": "vulnerability.critical",
      "status": "failed",
      "response_code": 500,
      "response_time_ms": 2000,
      "attempts": 3,
      "error": "Connection timeout",
      "created_at": "2025-12-21T15:35:00Z",
      "next_retry": "2025-12-21T16:35:00Z"
    }
  ],
  "total": 156
}

Wiederholungsrichtlinie

Fehlgeschlagene Zustellungen werden automatisch wiederholt:

Versuch	Verzögerung
1	Sofort
2	5 Minuten
3	30 Minuten
4	2 Stunden
5	8 Stunden

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert und der Webhook wird deaktiviert, wenn Fehler andauern.

Best Practices

1. Signaturen immer verifizieren, um Authentizität sicherzustellen
2. Schnell antworten (innerhalb von 30 Sekunden), um Timeouts zu vermeiden
3. 2xx-Status zurückgeben, um Empfang zu bestätigen
4. Asynchron verarbeiten für langwierige Operationen
5. Idempotenz implementieren unter Verwendung von Zustellungs-IDs
6. Zustellungsstatus überwachen und fehlerhafte Endpunkte zeitnah reparieren

Rate Limits

Tarif	Webhooks	Ereignisse/Stunde
Professional	5	1.000
Enterprise	Unbegrenzt	10.000