Webhooks
Assinatura
Há duas formas, que podem ser usadas juntas:
- Assinatura (recomendada): sempre enviada em
Notem-Assinatura. Prova a origem e que o corpo não foi alterado. Passos abaixo. - Chave de autorização (opção simples): se cadastrada, chega no cabeçalho escolhido (ex.:
Authorization: Bearer minha-chave). Basta comparar com o valor que você cadastrou. Não protege contra alteração do corpo; prefira a assinatura sempre que possível. - Confirmar pela API: em caso de dúvida, trate o webhook apenas como aviso e consulte o estado atual pela API (
https://app.notemfiscal.com.br/api/v1) com a sua chave de integração antes de agir.
Validação da assinatura
- Leia
tev1do cabeçalhoNotem-Assinatura. - Monte o texto
{t}.{corpo_bruto}— o corpo exatamente como recebido, antes de converter o JSON. - Calcule HMAC-SHA256 desse texto com o segredo
whsec_..., em hexadecimal minúsculo. - Compare com
v1usando comparação de tempo constante. - Recuse se
ttiver mais de 5 minutos de diferença do horário atual (proteção contra reenvio malicioso).
Durante a troca de segredo, a notem pode enviar duas assinaturas (v1=...,v1=...); aceite se qualquer uma for válida.
Exemplo em JavaScript (Node.js)
JavaScript
import crypto from "node:crypto";
// corpoBruto: o corpo exatamente como recebido (texto), antes de JSON.parse.
export function assinaturaValida(cabecalho, corpoBruto, segredo, agora = Date.now()) {
const partes = cabecalho.split(",").map((p) => p.trim().split("="));
const t = partes.find(([k]) => k === "t")?.[1];
const assinaturas = partes.filter(([k]) => k === "v1").map(([, v]) => v);
if (!t || assinaturas.length === 0) return false;
if (Math.abs(agora / 1000 - Number(t)) > 5 * 60) return false;
const esperada = crypto.createHmac("sha256", segredo).update(`${t}.${corpoBruto}`).digest("hex");
return assinaturas.some((v) =>
v.length === esperada.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(esperada)),
);
}
