Webhooks | cside docs

Hoe webhooks werken

Met webhooks kunt u c/side-notificaties ontvangen als HTTP POST-verzoeken naar een URL die u opgeeft. Wanneer een trigger wordt geactiveerd, stuurt c/side 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

Een webhook-bestemming toevoegen

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

Open het dashboard en navigeer naar Team Settings > Notifications
Maak een nieuwe notificatieconfiguratie aan of bewerk een bestaande
Klik onder Send To op Add destination en selecteer Webhook
Vul in het configuratiepaneel het volgende in:
- Endpoint 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
Klik op Save of Save & Test

De webhook-payload

Elk webhook-verzoek bevat een gestructureerde JSON-payload met de volgende velden:

Prop

Type

event

"alert.created"

The event code

sent_at

string

When the event was sent in ISO 8601 format

data

AlertCreatedObject

The data of the event

domain_id

string

The domain ID that the event is for

destination_id

string

The ID of the endpoint destination

Events

Hieronder staan de event-ID’s en hun payloads die met webhooks worden meegestuurd.

Event-ID’s

ID	Naam	`data`-object
alert.created	Alert Created	Alert Object

Event-objecten

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 c/side 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