Webhooks | cside docs

Hoe webhooks werken

cside Webhooks zijn een eenvoudige manier om notificaties te ontvangen over belangrijke evenementen in uw cside-account. Webhooks kunnen worden gebruikt om acties in uw applicatie te triggeren, berichten naar uw Discord- of Slack-kanalen te sturen, en meer.

Wanneer u een webhook-endpoint aanmaakt, sturen wij een POST-verzoek naar de URL die u heeft opgegeven. Het verzoek bevat een JSON-payload met informatie over het evenement dat de webhook heeft getriggerd.

De gegevensstructuur

Wij sturen u altijd 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

Evenementen

Hieronder staan de evenement-ID’s en hun payloads die met webhooks worden verzonden.

Evenement-ID’s

ID	Naam	`data`-object
alert.created	Melding aangemaakt	Meldingsobject

Evenementobjecten

HMAC-geheim (ook bekend als x-cside-signature)

Wij berekenen een HMAC ter plekke, met een SHA256-hash van de payload en uw webhook-geheim dat aan u is verstrekt toen u het webhook-endpoint voor het eerst aanmaakte. Deze handtekening is opgenomen in de x-cside-signature-header van het verzoek.

WIJ RADEN U STERK AAN DIT TE GEBRUIKEN OM TE VERIFIEREN DAT HET VERZOEK VAN cside AFKOMSTIG IS: Als u dit niet doet, kunt u kwetsbaar zijn voor replay-aanvallen.

Het HMAC-geheim verifieren

Als u JavaScript gebruikt, raden wij u aan ons JavaScript-pakket te gebruiken om de handtekening te verifieren. Wij hebben voorbeelden op die pagina die u helpen ermee aan de slag te gaan.

Als u geen JavaScript gebruikt, kunt u de handtekening verifieren door de HMAC SHA256-hash van de verzoekbody te berekenen met uw webhook-geheim en deze te vergelijken met de header (x-cside-signature) die wij bij elk verzoek meesturen.

Hier zijn enkele voorbeelden in verschillende talen:

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