Desarrolladores

API y webhooks

Conecta CloudSignLab con tus herramientas de informes y tickets. La API lee los registros de una organización; los webhooks avisan a tus sistemas cuando ocurre algo. Ambos forman parte del módulo Integraciones (Professional y superiores).

Autenticación

Los propietarios y administradores crean las claves de API en Organización → Integraciones. Envía la clave en la cabecera Authorization. Las claves solo leen, pertenecen a una organización y se pueden revocar en cualquier momento.

curl https://cloudsignlab.com/api/v1/risks?page=1&perPage=50 \
  -H "Authorization: Bearer csl_…"

{
  "data": [{ "id": "…", "number": 7, "title": "Ransomware on file server",
             "likelihood": 3, "impact": 5, "status": "open", … }],
  "total": 42, "page": 1, "perPage": 50
}

Las listas van paginadas (perPage hasta 100). Cada clave puede hacer 300 peticiones en 10 minutos; por encima, la API responde 429. Si las reglas de seguridad de la organización indican redes permitidas, las claves solo funcionan desde esas direcciones (las demás reciben 403).

Endpoints

GET /api/v1/organization	La organización de la clave.
GET /api/v1/risks	Registro de riesgos: probabilidad, impacto, valores residuales, tratamiento, estado.
GET /api/v1/controls	Controles con referencias a marcos y estado.
GET /api/v1/incidents	Incidentes con gravedad, estado y la marca NIS2.
GET /api/v1/suppliers	Registro de proveedores sin datos de contacto.
GET /api/v1/policies	Políticas publicadas con su versión.

Webhooks

Un webhook recibe un POST en JSON por cada evento al que está suscrito. El cuerpo contiene identificadores y un enlace, sin datos personales; los detalles se leen con la API.

incident.created
risk.created
policy.published
finding.created
task.created
supplier_check.answered
supplier_check.decided
check.failed

{
  "id": "5f0c…",
  "event": "incident.created",
  "occurredAt": "2026-10-01T08:15:00.000Z",
  "organization": { "id": "…", "name": "Example GmbH" },
  "target": { "id": "…", "url": "https://cloudsignlab.com/dashboard/…" }
}

Cada petición lleva X-CloudSignLab-Timestamp y X-CloudSignLab-Signature (HMAC-SHA256 de "timestamp.cuerpo" con el secreto de firma). Rechaza las peticiones con más de 5 minutos o con una firma incorrecta:

import { createHmac, timingSafeEqual } from "node:crypto";

const verify = (secret, timestamp, body, signature) => {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
};

Los canales de Slack y Microsoft Teams reciben en su lugar un mensaje corto con un enlace. Tras 20 entregas fallidas seguidas, una integración se detiene hasta que se vuelve a activar.