Webhooks API

Reciba notificaciones en tiempo real de eventos de CyberOrigen.

Professional y Enterprise

Los webhooks están disponibles en los planes Professional y Enterprise.

Descripción General

Los webhooks le permiten recibir callbacks HTTP cuando ocurren eventos en CyberOrigen. Configure endpoints para recibir notificaciones sobre escaneos, hallazgos, cambios de cumplimiento y más.

Endpoints

Método	Endpoint	Descripción
GET	/api/v1/webhooks	Listar webhooks
POST	/api/v1/webhooks	Crear webhook
GET	/api/v1/webhooks/{id}	Obtener detalles de webhook
PATCH	/api/v1/webhooks/{id}	Actualizar webhook
DELETE	/api/v1/webhooks/{id}	Eliminar webhook
POST	/api/v1/webhooks/{id}/test	Enviar evento de prueba
GET	/api/v1/webhooks/{id}/deliveries	Listar historial de entregas

Crear 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
}

Parámetros

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre descriptivo
url	string	Sí	URL del endpoint HTTPS
events	array	Sí	Eventos a los que suscribirse
secret	string	No	Secreto de firma para verificación
active	boolean	No	Habilitar/deshabilitar webhook

Respuesta

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

Eventos Disponibles

Eventos de Escaneo

Evento	Descripción
scan.created	Nuevo escaneo iniciado
scan.started	Ejecución de escaneo iniciada
scan.progress	Fase de escaneo completada
scan.completed	Escaneo finalizado exitosamente
scan.failed	Escaneo falló con error

Eventos de Vulnerabilidad

Evento	Descripción
vulnerability.found	Nueva vulnerabilidad descubierta
vulnerability.critical	Hallazgo de severidad crítica
vulnerability.high	Hallazgo de severidad alta
vulnerability.status_changed	Estado de hallazgo actualizado
vulnerability.resolved	Hallazgo marcado como resuelto

Eventos de Cumplimiento

Evento	Descripción
control.status_changed	Estado de control actualizado
evidence.uploaded	Nueva evidencia agregada
evidence.expiring	Evidencia próxima a expirar
framework.score_changed	Puntuación de cumplimiento cambiada
audit.request_created	Nueva solicitud de auditor

Eventos de Seguridad

Evento	Descripción
quarantine.threat_detected	Malware detectado en carga
user.login_failed	Intento de inicio de sesión fallido
user.mfa_disabled	MFA deshabilitado en cuenta

Carga Útil de Webhook

Todas las entregas de webhook incluyen:

{
  "id": "delivery_xyz789",
  "event": "scan.completed",
  "timestamp": "2025-12-21T15:30:00Z",
  "data": {
    // Datos específicos del evento
  }
}

Ejemplo: Escaneo Completado

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

Ejemplo: Vulnerabilidad Crítica

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

Verificación de Firma

Si proporciona un secret, CyberOrigen firma cada entrega con HMAC-SHA256.

Headers

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

Ejemplo de Verificación (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');
});

Ejemplo de Verificación (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

Probar Webhook

Envíe un evento de prueba para verificar su endpoint:

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

Respuesta

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

Historial de Entregas

Vea los intentos de entrega de webhook:

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

Respuesta

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

Política de Reintentos

Las entregas fallidas se reintentan automáticamente:

Intento	Retraso
1	Inmediato
2	5 minutos
3	30 minutos
4	2 horas
5	8 horas

Después de 5 intentos fallidos, la entrega se marca como fallida y el webhook se deshabilita si las fallas persisten.

Mejores Prácticas

1. Siempre verifique firmas para garantizar autenticidad
2. Responda rápidamente (dentro de 30 segundos) para evitar timeouts
3. Devuelva estado 2xx para confirmar recepción
4. Procese de forma asíncrona para operaciones de larga duración
5. Implemente idempotencia usando IDs de entrega
6. Monitoree estado de entrega y corrija endpoints fallidos rápidamente

Límites de Tasa

Plan	Webhooks	Eventos/Hora
Professional	5	1,000
Enterprise	Ilimitado	10,000