Webhooks

Comment fonctionnent les webhooks

Les webhooks vous permettent de recevoir les notifications cside sous forme de requêtes HTTP POST vers une URL que vous spécifiez. Lorsqu’un déclencheur s’active, cside envoie un payload JSON à votre endpoint webhook contenant les détails de l’événement.

Vous pouvez configurer les webhooks dans trois formats :

• JSON - payload JSON standard pour les intégrations personnalisées
• Slack - pré-formaté pour les canaux Slack
• Discord - pré-formaté pour les canaux Discord

Pour créer des tickets Jira à partir des webhooks, quel que soit votre plan, consultez Jira Automation.

Ajouter une destination webhook

Pour ajouter un webhook comme destination dans une notification config :

1. Ouvrez le tableau de bord et naviguez vers Team Settings > Notifications
2. Créez une nouvelle notification config ou modifiez-en une existante
3. Sous Send To, cliquez sur Add destination et sélectionnez Webhook
4. Dans le panneau Configuration, remplissez :
   • URL : l’URL où vous souhaitez recevoir les notifications webhook (par ex., https://example.com/cside/notify)
   • Secret : une clé secrète utilisée pour signer les requêtes webhook (utilisée pour la vérification HMAC)
   • Format : choisissez JSON, Slack ou Discord
5. Cliquez sur Save ou Save & Test

cside signe chaque requête avec l’en-tête x-cside-signature, mais ne peut pas ajouter d’en-têtes personnalisés. Si votre récepteur s’authentifie avec son propre en-tête, vérifiez s’il accepte aussi le token dans l’URL, comme le fait Jira Automation.

Le payload webhook

cside envoie une requête HTTP POST par événement, avec Content-Type: application/json et un en-tête x-cside-signature (voir la vérification HMAC). Chaque payload contient un champ event de premier niveau qui identifie le type d’événement, un horodatage, l’équipe ou le domaine auquel l’événement appartient et un objet data propre à l’événement.

Le champ qui contient l’horodatage varie selon l’événement : alert.created et les événements de digest utilisent timestamp, tandis que security_headers.changed utilise sent_at. Lisez d’abord event, puis analysez le reste du payload selon les tableaux ci-dessous. Traitez les champs inconnus comme facultatifs afin que de nouveaux champs ne cassent pas votre intégration.

Chaque payload JSON contient aussi deux champs lisibles par un humain, summary (un titre sur une ligne) et description (des détails sur plusieurs lignes), à la fois au premier niveau et répétés dans data. Utilisez-les pour remplir un ticket ou un message de chat sans construire votre propre texte pour chaque événement. Ils sont répétés dans data parce que Jira Automation traite de façon particulière une clé data de premier niveau.

IDs d’événements

Seuls alert.created, security_headers.changed et pci_report.available respectent les formats Slack et Discord. Les autres événements de digest sont toujours envoyés en JSON, quel que soit le format configuré sur la destination.

Save & Test envoie un exemple de payload alert.created avec le trigger_type du déclencheur de la règle, y compris pour les déclencheurs qui livrent normalement un digest. Son summary commence par [Test]. Security Headers Changed envoie à la place un exemple de payload security_headers.changed. Si votre endpoint répond par une erreur, le résultat du test affiche le code de statut HTTP qu’il a renvoyé.

Tous les horodatages sont des chaînes ISO 8601 en UTC. Les IDs sont des chaînes décimales.

alert.created

Envoyé pour chaque alerte levée par un déclencheur immédiat : Script Threat Detected, High-risk Vulnerability, Managed Flagged, Malicious Tag Manager, Malicious Outbound Connection et Vulnerable Script Detected lorsque la règle est configurée pour une livraison immédiate.

Valeurs de trigger_type :

Objet d’alerte

Les quatre champs vuln_* ne sont renseignés que pour vulnerable_script_detected et high_risk_vulnerability_detected. Pour tout autre trigger_type, ils valent 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

Envoyé par Security Headers Changed lorsque les en-têtes de sécurité observés sur les pages de paiement d’un domaine diffèrent entre deux fenêtres d’observation consécutives.

pci_report.available

Envoyé par PCI Report une fois le rapport de la période prêt, pour les domaines concernés qui ont des chemins de paiement configurés. Il est envoyé une seule fois par rapport ; une livraison rejetée n’est pas retentée. Chaque requête contient aussi un en-tête x-cside-delivery-id qui reste identique si le même rapport est livré à nouveau, ce qui vous permet de dédupliquer sur cette valeur.

csp_block_digest

Envoyé par Script Blocked by CSP avec les rapports de violation de Content Security Policy collectés sur la période. Rien n’est envoyé s’il n’y a eu aucune violation.

csp_policy_digest

Envoyé par CSP Policy Digest pour chaque domaine concerné dont la Content Security Policy recommandée a changé sur la période. Rien n’est envoyé si aucun domaine n’a changé.

vulnerable_script_digest

Envoyé par Vulnerable Script Detected en planification quotidienne ou hebdomadaire avec les vulnérabilités courantes (hors haut risque) détectées sur la période. Rien n’est envoyé s’il n’y a eu aucune détection.

outbound_connections_pending_review

Envoyé par Outbound Connections Pending Review avec le nombre de noms d’hôte sortants que votre équipe n’a pas encore approuvés dans l’inventaire des ressources. Rien n’est envoyé si rien n’est en attente.

Vérification HMAC

Chaque requête webhook inclut un en-tête x-cside-signature contenant un hash HMAC SHA256 du corps de la requête, signé avec le secret que vous avez fourni lors de la création de la destination webhook.

Vous devriez toujours vérifier cette signature pour confirmer que la requête provient de cside et prévenir les attaques par rejeu.

Comment vérifier la signature

Si vous utilisez JavaScript, utilisez notre package JavaScript pour une vérification intégrée.

Pour les autres langages, calculez le hash HMAC SHA256 du corps brut de la requête en utilisant votre secret webhook, puis comparez-le à la valeur de l’en-tête 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