Webhooks

Cómo funcionan los webhooks

Los webhooks te permiten recibir notificaciones de cside como solicitudes HTTP POST a una URL que especifiques. Cuando se activa un disparador, cside envía un payload JSON a tu endpoint de webhook con detalles sobre el evento.

Puedes configurar webhooks en tres formatos:

• JSON - payload JSON estándar para integraciones personalizadas
• Slack - preformateado para canales de Slack
• Discord - preformateado para canales de Discord

Para crear elementos de trabajo de Jira a partir de webhooks en cualquier plan, consulta Jira Automation.

Agregar un destino de webhook

Para agregar un webhook como destino en una configuración de notificación:

1. Abre el panel de control y navega a Team Settings > Notifications
2. Crea una nueva configuración de notificación o edita una existente
3. En Send To, haz clic en Add destination y selecciona Webhook
4. En el panel de Configuration, completa:
   • URL: la URL donde quieres recibir las notificaciones de webhook (por ejemplo, https://example.com/cside/notify)
   • Secret: una clave secreta usada para firmar las solicitudes de webhook (usada para la verificación HMAC)
   • Format: elige JSON, Slack o Discord
5. Haz clic en Save o Save & Test

cside firma cada solicitud con el encabezado x-cside-signature, pero no puede agregar encabezados personalizados. Si tu receptor se autentica con su propio encabezado, comprueba si también acepta el token en la URL, como hace Jira Automation.

El payload del webhook

cside envía una solicitud HTTP POST por evento, con Content-Type: application/json y un encabezado x-cside-signature (consulta la verificación HMAC). Cada payload incluye un campo event de nivel superior que identifica el tipo de evento, una marca de tiempo, el equipo o dominio al que pertenece el evento y un objeto data específico del evento.

El campo que contiene la marca de tiempo varía según el evento: alert.created y los eventos de resumen usan timestamp, mientras que security_headers.changed usa sent_at. Lee primero event y después analiza el resto del payload según las tablas siguientes. Trata los campos desconocidos como opcionales para que los campos nuevos no rompan tu integración.

Cada payload JSON incluye además dos campos legibles para personas, summary (un título de una línea) y description (detalles en varias líneas), tanto en el nivel superior como repetidos dentro de data. Úsalos para rellenar un ticket o un mensaje de chat sin tener que construir tu propio texto para cada evento. Se repiten dentro de data porque Jira Automation trata de forma especial una clave data de nivel superior.

IDs de eventos

Solo alert.created, security_headers.changed y pci_report.available respetan los formatos Slack y Discord. Los demás eventos de resumen se envían siempre como JSON, sea cual sea el formato configurado en el destino.

Save & Test envía un payload alert.created de ejemplo con el trigger_type del disparador de la regla, incluso para los disparadores que normalmente entregan un resumen. Su summary empieza por [Test]. Security Headers Changed envía en su lugar un payload security_headers.changed de ejemplo. Si tu endpoint responde con un error, el resultado de la prueba muestra el código de estado HTTP que devolvió.

Todas las marcas de tiempo son cadenas ISO 8601 en UTC. Los IDs son cadenas decimales.

alert.created

Se envía por cada alerta que genera un disparador inmediato: Script Threat Detected, High-risk Vulnerability, Managed Flagged, Malicious Tag Manager, Malicious Outbound Connection y Vulnerable Script Detected cuando la regla está configurada para entregar de inmediato.

Valores de trigger_type:

Objeto de alerta

Los cuatro campos vuln_* solo se rellenan para vulnerable_script_detected y high_risk_vulnerability_detected. Para cualquier otro trigger_type son null.

{
  "event": "alert.created",
  "timestamp": "2026-09-17T10:15:30.123456Z",
  "domain_id": "1897425263682514945",
  "domain": "checkout.example.com",
  "trigger_type": "high_risk_vulnerability_detected",
  "summary": "[cside] High-risk Vulnerability: CVE-2024-1234 on checkout.example.com",
  "description": "cside detected a high-risk vulnerability on checkout.example.com: lodash. Severity: High.\n\nThis is a high-risk finding (malware or a high-severity vulnerability). Investigate it promptly: if it is malware, remove the script immediately and rotate any credentials it may have accessed; otherwise prioritize updating or removing the affected dependency.",
  "data": {
    "summary": "[cside] High-risk Vulnerability: CVE-2024-1234 on checkout.example.com",
    "description": "cside detected a high-risk vulnerability on checkout.example.com: lodash. Severity: High.\n\nThis is a high-risk finding (malware or a high-severity vulnerability). Investigate it promptly: if it is malware, remove the script immediately and rotate any credentials it may have accessed; otherwise prioritize updating or removing the affected dependency.",
    "domain": "checkout.example.com",
    "trigger_type": "high_risk_vulnerability_detected",
    "target_type": "URL",
    "target": "https://cdn.example.com/lodash.js",
    "action": "alert",
    "ruleset_id": "ruleset_vulnerability_detected",
    "ruleset_name": "Vulnerability Detected",
    "ruleset_description": "A script with a known vulnerability was loaded",
    "script_urls": ["https://cdn.example.com/lodash.js"],
    "vuln_cve_id": "CVE-2024-1234",
    "vuln_package": "lodash",
    "vuln_severity": "HIGH",
    "vuln_reference_url": "https://osv.dev/vulnerability/CVE-2024-1234"
  },
  "destination_id": "1897425263682514950"
}

security_headers.changed

Lo envía Security Headers Changed cuando las cabeceras de seguridad observadas en las páginas de checkout de un dominio difieren entre dos ventanas de observación consecutivas.

pci_report.available

Lo envía PCI Report cuando el informe del periodo está listo, para los dominios en alcance que tienen rutas de checkout configuradas. Se envía una vez por informe; una entrega rechazada no se reintenta. Cada solicitud incluye además un encabezado x-cside-delivery-id que no cambia si el mismo informe se entrega de nuevo, así que puedes usarlo para eliminar duplicados.

csp_block_digest

Lo envía Script Blocked by CSP con los informes de violación de Content Security Policy recopilados en el periodo. No se envía nada si no hubo violaciones.

csp_policy_digest

Lo envía CSP Policy Digest por cada dominio en alcance cuya Content Security Policy recomendada cambió en el periodo. No se envía nada si ningún dominio cambió.

vulnerable_script_digest

Lo envía Vulnerable Script Detected en una programación diaria o semanal con los hallazgos de vulnerabilidades rutinarias (no de alto riesgo) del periodo. No se envía nada si no hubo hallazgos.

outbound_connections_pending_review

Lo envía Outbound Connections Pending Review con el número de hostnames salientes que tu equipo todavía no ha aprobado en Resources inventory. No se envía nada si no hay nada pendiente.

Verificación HMAC

Cada solicitud de webhook incluye un encabezado x-cside-signature que contiene un hash HMAC SHA256 del cuerpo de la solicitud, firmado con el secret que proporcionaste al crear el destino de webhook.

Siempre debes verificar esta firma para confirmar que la solicitud proviene de cside y prevenir ataques de repetición.

Cómo verificar la firma

Si estás usando JavaScript, usa nuestro paquete JavaScript para verificación integrada.

Para otros lenguajes, calcula el hash HMAC SHA256 del cuerpo crudo de la solicitud usando tu secret de webhook, y luego compáralo con el valor del encabezado x-cside-signature.

async function verifyHmac(body: string, signature: string, secret: string) {
	const encoder = new TextEncoder();
	const encodedBody = encoder.encode(body);

	const key = await crypto.subtle.importKey(
		"raw",
		encoder.encode(secret),
		{ name: "HMAC", hash: "SHA-256" },
		false,
		["sign"]
	);

	const signatureBuffer = await crypto.subtle.sign("HMAC", key, encodedBody);

	const finalSig = Array.from(new Uint8Array(signatureBuffer))
		.map((byte) => byte.toString(16).padStart(2, "0"))
		.join("");

	return signature.toLowerCase() === finalSig;
}

fn verify_hmac(body: &str, signature: &str, secret: &str) -> Result<(), &'static str> {
      let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).map_err(|_| "Invalid secret")?;
      mac.update(body.as_bytes());
      let result = mac.finalize();
      let code_bytes = result.into_bytes();
      let final_sig = hex::encode(code_bytes);

      if signature.to_lowercase() == final_sig {
          Ok(())
      } else {
          Err("Invalid signature")
      }
  }

  // Add to Cargo.toml:
  // [dependencies]
  // hmac = "0.12"
  // sha2 = "0.10"
  // hex = "0.4"

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "strings"
)

func verifyHmac(body, signature, secret string) bool {
	h := hmac.New(sha256.New, []byte(secret))
	h.Write([]byte(body))
	finalSig := hex.EncodeToString(h.Sum(nil))

	return strings.ToLower(signature) == finalSig
}

defmodule HmacVerifier do
	def verify_hmac(body, signature, secret) do
		final_sig =
			:crypto.mac(:hmac, :sha256, secret, body)
			|> Base.encode16(case: :lower)

			String.downcase(signature) == final_sig
	end
end

import hmac
import hashlib
import secrets

def verify_hmac(body: str, signature: str, secret: str) -> bool:
	final_sig = hmac.new(
		secret.encode('utf-8'),
		body.encode('utf-8'),
		hashlib.sha256
	).hexdigest()

	return signature.lower() == final_sig