Webhooks

Hoe webhooks werken

Met webhooks kunt u cside-notificaties ontvangen als HTTP POST-verzoeken naar een URL die u opgeeft. Wanneer een trigger wordt geactiveerd, stuurt cside een JSON-payload naar uw webhook-endpoint met details over de gebeurtenis.

U kunt webhooks in drie formaten configureren:

• JSON - standaard JSON-payload voor aangepaste integraties
• Slack - voorgeformatteerd voor Slack-kanalen
• Discord - voorgeformatteerd voor Discord-kanalen

Zie Jira Automation om op elk plan Jira-werkitems aan te maken vanuit webhooks.

Een webhook-bestemming toevoegen

Om een webhook als bestemming toe te voegen aan een notificatieconfiguratie:

1. Open het dashboard en navigeer naar Team Settings > Notifications
2. Maak een nieuwe notificatieconfiguratie aan of bewerk een bestaande
3. Klik onder Send To op Add destination en selecteer Webhook
4. Vul in het configuratiepaneel het volgende in:
   • URL: de URL waar u webhook-notificaties wilt ontvangen (bijv. https://example.com/cside/notify)
   • Secret: een geheime sleutel die wordt gebruikt om webhook-verzoeken te ondertekenen (gebruikt voor HMAC-verificatie)
   • Format: kies JSON, Slack of Discord
5. Klik op Save of Save & Test

cside ondertekent elk verzoek met de x-cside-signature-header, maar kan geen aangepaste headers toevoegen. Als uw ontvanger authenticeert met een eigen header, controleer dan of deze het token ook in de URL accepteert, zoals Jira Automation doet.

De webhook-payload

cside stuurt één HTTP POST per gebeurtenis, met Content-Type: application/json en een x-cside-signature-header (zie HMAC-verificatie). Elke payload bevat een event-veld op het hoogste niveau dat het type gebeurtenis aanduidt, een tijdstempel, het team of domein waar de gebeurtenis bij hoort en een gebeurtenisspecifiek data-object.

Het veld dat de tijdstempel bevat verschilt per gebeurtenis: alert.created en de samenvattingsgebeurtenissen gebruiken timestamp, terwijl security_headers.changed sent_at gebruikt. Lees eerst event en verwerk daarna de rest van de payload volgens de tabellen hieronder. Behandel onbekende velden als optioneel, zodat nieuwe velden uw integratie niet breken.

Elke JSON-payload bevat ook twee voor mensen leesbare velden, summary (een titel van één regel) en description (details over meerdere regels), zowel op het hoogste niveau als herhaald binnen data. Gebruik ze om een ticket of chatbericht in te vullen zonder per gebeurtenis uw eigen tekst op te bouwen. Ze worden binnen data herhaald omdat Jira Automation een data-sleutel op het hoogste niveau speciaal behandelt.

Event-ID’s

Alleen alert.created, security_headers.changed en pci_report.available respecteren de formaten Slack en Discord. De andere samenvattingsgebeurtenissen worden altijd als JSON verstuurd, ongeacht het formaat dat voor de bestemming is ingesteld.

Save & Test stuurt een voorbeeldpayload van alert.created met het trigger_type van de trigger van de regel, ook voor triggers die normaal een samenvatting afleveren. De summary daarvan begint met [Test]. Security Headers Changed stuurt in plaats daarvan een voorbeeldpayload van security_headers.changed. Als uw endpoint met een fout antwoordt, toont het testresultaat de HTTP-statuscode die het teruggaf.

Alle tijdstempels zijn ISO 8601-tekenreeksen in UTC. ID’s zijn decimale tekenreeksen.

alert.created

Wordt verstuurd voor elke waarschuwing die een directe trigger genereert: Script Threat Detected, High-risk Vulnerability, Managed Flagged, Malicious Tag Manager, Malicious Outbound Connection en Vulnerable Script Detected wanneer de regel is ingesteld op directe aflevering.

Waarden van trigger_type:

Alert-object

De vier vuln_*-velden worden alleen gevuld voor vulnerable_script_detected en high_risk_vulnerability_detected. Voor elk ander trigger_type zijn ze 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

Wordt verstuurd door Security Headers Changed wanneer de security headers die op de checkout-pagina’s van een domein worden waargenomen verschillen tussen twee opeenvolgende observatievensters.

pci_report.available

Wordt verstuurd door PCI Report zodra het rapport voor de periode klaar is, voor de domeinen binnen bereik waarvoor checkout-paden zijn ingesteld. Het wordt één keer per rapport verstuurd; een geweigerde aflevering wordt niet opnieuw geprobeerd. Elk verzoek bevat ook een x-cside-delivery-id-header die gelijk blijft als hetzelfde rapport opnieuw wordt afgeleverd, zodat u daarop kunt dedupliceren.

csp_block_digest

Wordt verstuurd door Script Blocked by CSP met de Content Security Policy-overtredingsrapporten die in de periode zijn verzameld. Er wordt niets verstuurd als er geen overtredingen waren.

csp_policy_digest

Wordt verstuurd door CSP Policy Digest voor elk domein binnen bereik waarvan het aanbevolen Content Security Policy in de periode is gewijzigd. Er wordt niets verstuurd als er geen domein is gewijzigd.

vulnerable_script_digest

Wordt verstuurd door Vulnerable Script Detected met een dagelijks of wekelijks schema, met de routinematige (niet high-risk) kwetsbaarheidsbevindingen uit de periode. Er wordt niets verstuurd als er geen bevindingen waren.

outbound_connections_pending_review

Wordt verstuurd door Outbound Connections Pending Review met het aantal uitgaande hostnames dat uw team nog niet heeft goedgekeurd in Resources inventory. Er wordt niets verstuurd als er niets openstaat.

HMAC-verificatie

Elk webhook-verzoek bevat een x-cside-signature-header met een HMAC SHA256-hash van de verzoekbody, ondertekend met het secret dat u heeft opgegeven bij het aanmaken van de webhook-bestemming.

U dient deze handtekening altijd te verifiëren om te bevestigen dat het verzoek van cside afkomstig is en replay-aanvallen te voorkomen.

Hoe de handtekening te verifiëren

Als u JavaScript gebruikt, gebruik dan ons JavaScript-pakket voor ingebouwde verificatie.

Voor andere talen berekent u de HMAC SHA256-hash van de ruwe verzoekbody met uw webhook-secret en vergelijkt u deze met de waarde van de x-cside-signature-header.

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