Webhooks | cside docs

Comment fonctionnent les webhooks

Les webhooks vous permettent de recevoir les notifications c/side sous forme de requêtes HTTP POST vers une URL que vous spécifiez. Lorsqu’un déclencheur se déclenche, c/side 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

Ajouter une destination webhook

Pour ajouter un webhook comme destination dans une notification config :

Ouvrez le tableau de bord et naviguez vers Team Settings > Notifications
Créez une nouvelle notification config ou modifiez-en une existante
Sous Send To, cliquez sur Add destination et sélectionnez Webhook
Dans le panneau Configuration, remplissez :
- Endpoint 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
Cliquez sur Save ou Save & Test

Le payload webhook

Chaque requête webhook contient un payload JSON structuré avec les champs suivants :

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

Voici les IDs d’événements et leurs payloads envoyés avec les webhooks.

Event IDs

ID	Nom	Objet `data`
alert.created	Alert Created	Alert Object

Objets d’événements

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