Webhooks | cside docs

Como os Webhooks Funcionam

Os Webhooks do cside são uma maneira fácil de receber notificações sobre eventos importantes na sua conta cside. Os webhooks podem ser usados para acionar ações na sua aplicação, enviar mensagens para seus canais Discord ou Slack, e muito mais.

Quando você cria um endpoint de webhook, enviaremos uma requisição POST para a URL que você especificou. A requisição conterá um payload JSON com informações sobre o evento que acionou o webhook.

A Estrutura de Dados

Sempre enviaremos um payload JSON estruturado com os seguintes campos:

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

Eventos

Abaixo estão os IDs de eventos e seus payloads que serão enviados com webhooks.

IDs de Eventos

ID	Nome	Objeto `data`
alert.created	Alerta Criado	Objeto Alert

Objetos de Eventos

HMAC Secret (também conhecido como x-cside-signature)

Calculamos um HMAC em tempo real, usando um hash SHA256 do payload e o secret do seu webhook que foi fornecido quando você criou o endpoint de webhook pela primeira vez. Essa assinatura está incluída no cabeçalho x-cside-signature da requisição.

RECOMENDAMOS FORTEMENTE QUE VOCÊ USE ISSO PARA VERIFICAR SE A REQUISIÇÃO VEM DO cside: Não fazer isso pode deixá-lo vulnerável a ataques de replay.

Verificando o HMAC secret

Se você está usando JavaScript, sugerimos que use nosso Pacote JavaScript para ajudá-lo a verificar a assinatura. Fornecemos exemplos nessa página que ajudarão você a começar.

Se você não está usando JavaScript, pode verificar a assinatura calculando o hash HMAC SHA256 do corpo da requisição usando o secret do seu webhook e comparando-o com o cabeçalho (x-cside-signature) que enviamos com cada requisição.

Aqui estão alguns exemplos em diferentes linguagens:

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