Webhooks API

Receive real-time notifications for CyberOrigen events.

Professional and Enterprise

Webhooks are available on Professional and Enterprise plans.

Overview

Webhooks allow you to receive HTTP callbacks when events occur in CyberOrigen. Configure endpoints to receive notifications about scans, findings, compliance changes, and more.

Endpoints

Method	Endpoint	Description
GET	/api/v1/webhooks	List webhooks
POST	/api/v1/webhooks	Create webhook
GET	/api/v1/webhooks/{id}	Get webhook details
PATCH	/api/v1/webhooks/{id}	Update webhook
DELETE	/api/v1/webhooks/{id}	Delete webhook
POST	/api/v1/webhooks/{id}/test	Send test event
GET	/api/v1/webhooks/{id}/deliveries	List delivery history

Create Webhook

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
}

Parameters

Field	Type	Required	Description
name	string	Yes	Descriptive name
url	string	Yes	HTTPS endpoint URL
events	array	Yes	Events to subscribe to
secret	string	No	Signing secret for verification
active	boolean	No	Enable/disable webhook

Response

{
  "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"
}

Available Events

Scan Events

Event	Description
scan.created	New scan initiated
scan.started	Scan execution started
scan.progress	Scan phase completed
scan.completed	Scan finished successfully
scan.failed	Scan failed with error

Vulnerability Events

Event	Description
vulnerability.found	New vulnerability discovered
vulnerability.critical	Critical severity finding
vulnerability.high	High severity finding
vulnerability.status_changed	Finding status updated
vulnerability.resolved	Finding marked resolved

Compliance Events

Event	Description
control.status_changed	Control status updated
evidence.uploaded	New evidence added
evidence.expiring	Evidence approaching expiration
framework.score_changed	Compliance score changed
audit.request_created	New auditor request

Security Events

Event	Description
quarantine.threat_detected	Malware detected in upload
user.login_failed	Failed login attempt
user.mfa_disabled	MFA disabled on account

Webhook Payload

All webhook deliveries include:

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

Example: Scan Completed

{
  "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
    }
  }
}

Example: Critical Vulnerability

{
  "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"
  }
}

Signature Verification

If you provide a secret, CyberOrigen signs each delivery with HMAC-SHA256.

Headers

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

Verification Example (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');
});

Verification Example (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

Test Webhook

Send a test event to verify your endpoint:

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

Response

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

Delivery History

View webhook delivery attempts:

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

Response

{
  "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
}

Retry Policy

Failed deliveries are retried automatically:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	8 hours

After 5 failed attempts, the delivery is marked as failed and the webhook is disabled if failures persist.

Best Practices

1. Always verify signatures to ensure authenticity
2. Respond quickly (within 30 seconds) to avoid timeouts
3. Return 2xx status to acknowledge receipt
4. Process asynchronously for long-running operations
5. Implement idempotency using delivery IDs
6. Monitor delivery status and fix failing endpoints promptly

Rate Limits

Plan	Webhooks	Events/Hour
Professional	5	1,000
Enterprise	Unlimited	10,000