Webhooks

Resumo

Os webhooks avisam seu sistema sobre o que acontece na Coreli em tempo quase real. A configuração é por conta: no painel, abra Configurações → Webhook.

• Enviamos uma requisição HTTP com corpo em JSON para a URL que você informar.
• Só entram na fila os tipos de evento que você marcar na configuração.
• A URL deve ser HTTPS. HTTP (incluindo 127.0.0.1 e localhost) não é aceito.

Lista de tipos de evento: secção Eventos abaixo.

Corpo (JSON)

Todos os eventos usam o mesmo envelope:

Strings longas em data podem ser truncadas internamente para proteger seu endpoint.

Cabeçalhos

O segredo HMAC é o signing secret (whsec_...) mostrado somente uma vez ao criar o webhook, ao regenerar o segredo ou na primeira gravação.

Verificação da assinatura

1. Leia o corpo da requisição como bytes brutos (antes de parsear JSON).
2. Calcule HMAC-SHA256(corpo_bruto, signing_secret).
3. Compare com o valor após v1= em X-Coreli-Signature (hex minúsculo), de forma constant-time quando possível.

Exemplo em Node.js (middleware que preserva raw body):

import crypto from "crypto";

function coreliVerify(rawBody, headerSig, secret) {
  if (!headerSig || typeof headerSig !== "string" || !headerSig.startsWith("v1=")) return false;
  const want = headerSig.slice(3);
  const got = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  try {
    return crypto.timingSafeEqual(Buffer.from(want, "hex"), Buffer.from(got, "hex"));
  } catch {
    return false;
  }
}

Boas práticas

• Responda 2xx rápido e processe o evento em fila no seu lado.
• Trate reentregas: use X-Coreli-Webhook-Id para idempotência.
• Guarde o segredo em variável de ambiente e mantenha o endpoint em HTTPS.