API Webhooks

Recevez des notifications en temps réel pour les événements CyberOrigen.

Professionnel et Entreprise

Les webhooks sont disponibles sur les plans Professionnel et Entreprise.

Vue d'ensemble

Les webhooks vous permettent de recevoir des rappels HTTP lorsque des événements se produisent dans CyberOrigen. Configurez des points de terminaison pour recevoir des notifications sur les analyses, les découvertes, les changements de conformité, et plus encore.

Points de terminaison

Méthode	Point de terminaison	Description
GET	/api/v1/webhooks	Lister les webhooks
POST	/api/v1/webhooks	Créer un webhook
GET	/api/v1/webhooks/{id}	Obtenir les détails d'un webhook
PATCH	/api/v1/webhooks/{id}	Mettre à jour un webhook
DELETE	/api/v1/webhooks/{id}	Supprimer un webhook
POST	/api/v1/webhooks/{id}/test	Envoyer un événement de test
GET	/api/v1/webhooks/{id}/deliveries	Lister l'historique des livraisons

Créer un 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
}

Paramètres

Champ	Type	Requis	Description
name	string	Oui	Nom descriptif
url	string	Oui	URL du point de terminaison HTTPS
events	array	Oui	Événements auxquels s'abonner
secret	string	Non	Secret de signature pour la vérification
active	boolean	Non	Activer/désactiver le webhook

Réponse

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

Événements disponibles

Événements d'analyse

Événement	Description
scan.created	Nouvelle analyse initiée
scan.started	Exécution de l'analyse démarrée
scan.progress	Phase d'analyse terminée
scan.completed	Analyse terminée avec succès
scan.failed	Échec de l'analyse avec erreur

Événements de vulnérabilité

Événement	Description
vulnerability.found	Nouvelle vulnérabilité découverte
vulnerability.critical	Découverte de sévérité critique
vulnerability.high	Découverte de sévérité élevée
vulnerability.status_changed	Statut de la découverte mis à jour
vulnerability.resolved	Découverte marquée comme résolue

Événements de conformité

Événement	Description
control.status_changed	Statut du contrôle mis à jour
evidence.uploaded	Nouvelle preuve ajoutée
evidence.expiring	Preuve approchant de l'expiration
framework.score_changed	Score de conformité modifié
audit.request_created	Nouvelle demande d'auditeur

Événements de sécurité

Événement	Description
quarantine.threat_detected	Malware détecté dans le téléchargement
user.login_failed	Tentative de connexion échouée
user.mfa_disabled	MFA désactivé sur le compte

Charge utile du webhook

Toutes les livraisons de webhook incluent :

{
  "id": "delivery_xyz789",
  "event": "scan.completed",
  "timestamp": "2025-12-21T15:30:00Z",
  "data": {
    // Données spécifiques à l'événement
  }
}

Exemple : Analyse terminée

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

Exemple : Vulnérabilité critique

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

Vérification de signature

Si vous fournissez un secret, CyberOrigen signe chaque livraison avec HMAC-SHA256.

En-têtes

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

Exemple de vérification (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');
});

Exemple de vérification (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

Tester un webhook

Envoyer un événement de test pour vérifier votre point de terminaison :

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

Réponse

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

Historique des livraisons

Voir les tentatives de livraison de webhook :

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

Réponse

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

Politique de nouvelle tentative

Les livraisons échouées sont automatiquement retentées :

Tentative	Délai
1	Immédiat
2	5 minutes
3	30 minutes
4	2 heures
5	8 heures

Après 5 tentatives échouées, la livraison est marquée comme échouée et le webhook est désactivé si les échecs persistent.

Bonnes pratiques

1. Toujours vérifier les signatures pour garantir l'authenticité
2. Répondre rapidement (dans les 30 secondes) pour éviter les délais d'attente
3. Retourner un statut 2xx pour accuser réception
4. Traiter de manière asynchrone pour les opérations de longue durée
5. Implémenter l'idempotence en utilisant les identifiants de livraison
6. Surveiller l'état des livraisons et corriger rapidement les points de terminaison défaillants

Limites de taux

Plan	Webhooks	Événements/Heure
Professional	5	1 000
Enterprise	Illimité	10 000