Webhooks | cside docs

Comment fonctionnent les Webhooks

Les Webhooks cside sont un moyen simple de recevoir des notifications sur les evenements importants de votre compte cside. Les webhooks peuvent etre utilises pour declencher des actions dans votre application, envoyer des messages a vos canaux Discord ou Slack, et bien plus encore.

Lorsque vous creez un point de terminaison webhook, nous enverrons une requete POST a l’URL que vous avez specifiee. La requete contiendra un payload JSON avec des informations sur l’evenement qui a declenche le webhook.

La structure des donnees

Nous vous enverrons toujours un payload JSON structure 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

Evenements

Voici les identifiants d’evenements et leurs payloads qui seront envoyes avec les webhooks.

Identifiants d’evenements

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

Objets d’evenements

Secret HMAC (alias x-cside-signature)

Nous calculons un HMAC a la volee, en utilisant un hash SHA256 du payload et votre secret webhook qui vous a ete fourni lors de la creation initiale du point de terminaison webhook. Cette signature est incluse dans l’en-tete x-cside-signature de la requete.

NOUS VOUS RECOMMANDONS FORTEMENT D’UTILISER CECI POUR VERIFIER QUE LA REQUETE PROVIENT DE cside : Ne pas le faire pourrait vous rendre vulnerable aux attaques par rejeu.

Verification du secret HMAC

Si vous utilisez JavaScript, nous vous suggerons d’utiliser notre package JavaScript pour vous aider a verifier la signature. Nous avons fourni des exemples sur cette page qui vous aideront a demarrer.

Si vous n’utilisez pas JavaScript, vous pouvez verifier la signature en calculant le hash HMAC SHA256 du corps de la requete en utilisant votre secret webhook, et en le comparant a l’en-tete (x-cside-signature) que nous envoyons avec chaque requete.

Voici quelques exemples dans differents langages :

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