Webhooks

Os cabeçalhos que enviamos

• Content-Type: application/json
• X-Ideaudit-Event — um entre audit.finalized, audit.outcome.recorded, entity.created.
• X-Ideaudit-Signature: sha256=<hex> — veja abaixo.
• X-Ideaudit-Endpoint: <uuid> — o id do seu endpoint, para rotear em receptores com vários endpoints.

Verificando a assinatura (Node)

A assinatura é HMAC-SHA256(secret, raw_request_body) em hex, prefixada com sha256=. Confira contra os bytes crus do corpo — nunca contra o JSON reserializado.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, signatureHeader: string, rawBody: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Verificando a assinatura (Python)

import hmac, hashlib

def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Eventos de teste

O botão “Testar” do dashboard usa o id da sua auditoria finalizada mais recente (ou o UUID zerado, se você não tiver nenhuma) e acrescenta isTest: true ao payload. Cheque esse campo no seu receptor para pular efeitos colaterais.

Desativação automática

Depois de 5 respostas seguidas fora da faixa 2xx, viramos active = false e marcamos o endpoint com um selo de desativado. Conserte o receptor e clique em Reativar em Configurações → Webhooks. O histórico recente de entregas — status e corpo da resposta — fica num painel expansível por endpoint.