Motor de Emissão

Webhooks

O motor avisa o seu sistema quando algo muda: nota autorizada, rejeitada, cancelada, evento registrado. Assim você não precisa ficar consultando.

Cadastrar

Informe uma URL https pública e os eventos que ela recebe (webhook.json):

{
  "url": "https://seu-sistema.exemplo.com.br/motor/webhooks",
  "eventos": ["documento.autorizado", "documento.rejeitado", "documento.cancelado"]
}
curl -s $MOTOR/v1/webhooks \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d @webhook.json | jq

A resposta traz o segredo (whsec_...) uma única vez. Guarde-o junto das outras credenciais do seu sistema: ele confere a assinatura das entregas e não aparece de novo na listagem.

Uma conta tem até 10 webhooks. Para trocar a URL ou o segredo, cadastre um novo e remova o antigo com DELETE /v1/webhooks/{id}.

Eventos

EventoQuando
documento.autorizadoA nota foi autorizada. O XML e o PDF já estão disponíveis.
documento.rejeitadoA SEFAZ (ou o Sistema Nacional) rejeitou a nota. Veja codigo_sefaz, motivo_sefaz e rejeicao. O número continua reservado.
documento.denegadoUso denegado por irregularidade fiscal do emitente ou do destinatário. A nota existe, mas não vale, e o número não volta.
documento.contingenciaNFC-e emitida em contingência offline; o cupom pode ser entregue e será transmitido quando a SEFAZ voltar.
documento.canceladoO cancelamento (ou a substituição da NFS-e) foi registrado.
evento.registradoUm evento da nota (cancelamento, carta de correção) foi registrado.
evento.rejeitadoA SEFAZ recusou o evento; a nota continua como estava.
inutilizacao.concluidaA faixa de números foi inutilizada.
certificado.vencendoO certificado A1 de uma emissora está perto de vencer.

A entrega

Cada entrega é um POST com o corpo em JSON:

{
  "id": "0b6f1c1e-6a52-4a5e-9d0c-2f8f4f3b9a10",
  "tipo": "documento.autorizado",
  "criado_em": "2026-10-20T14:03:11Z",
  "dados": { "id": "...", "status": "autorizado", "chave": "...", "protocolo": "...", "id_externo": "pedido-1001" }
}

Em dados vem o documento como em GET /v1/documentos/{id}; o id_externo liga a nota ao pedido do seu sistema. Os cabeçalhos:

Responder e repetir

Responda 2xx em até 10 segundos. Qualquer outra resposta (ou nenhuma) faz o motor tentar de novo, com espera crescente, por até 15 tentativas ao longo de várias horas. Por isso:

Conferir a assinatura

Confira toda entrega antes de confiar nela: recalcule o HMAC sobre o corpo bruto, exatamente como chegou (antes de converter o JSON), compare em tempo constante e recuse t com mais de 5 minutos de diferença do seu relógio.

Node.js

const crypto = require("crypto");

function assinaturaValida(segredo, cabecalho, corpoBruto) {
  const partes = Object.fromEntries(cabecalho.split(",").map(p => p.trim().split("=")));
  const t = Number(partes.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = crypto.createHmac("sha256", segredo).update(`${t}.`).update(corpoBruto).digest("hex");
  const recebido = Buffer.from(partes.v1 || "", "hex");
  return recebido.length === 32 && crypto.timingSafeEqual(recebido, Buffer.from(esperado, "hex"));
}

// Express: use express.raw({ type: "application/json" }) na rota do webhook.

PHP

function assinaturaValida(string $segredo, string $cabecalho, string $corpoBruto): bool
{
    parse_str(str_replace(',', '&', $cabecalho), $partes);
    $t = (int) ($partes['t'] ?? 0);
    if ($t === 0 || abs(time() - $t) > 300) {
        return false;
    }
    $esperado = hash_hmac('sha256', $t . '.' . $corpoBruto, $segredo);
    return hash_equals($esperado, $partes['v1'] ?? '');
}

// $corpoBruto = file_get_contents('php://input');
// $cabecalho  = $_SERVER['HTTP_MOTOR_ASSINATURA'];

Python

import hashlib, hmac, time

def assinatura_valida(segredo: bytes, cabecalho: str, corpo_bruto: bytes) -> bool:
    partes = dict(p.strip().split("=", 1) for p in cabecalho.split(","))
    t = int(partes.get("t", "0"))
    if t == 0 or abs(time.time() - t) > 300:
        return False
    esperado = hmac.new(segredo, f"{t}.".encode() + corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes.get("v1", ""))

Go

func assinaturaValida(segredo []byte, cabecalho string, corpoBruto []byte) bool {
	var t, v1 string
	for _, parte := range strings.Split(cabecalho, ",") {
		chave, valor, _ := strings.Cut(strings.TrimSpace(parte), "=")
		switch chave {
		case "t":
			t = valor
		case "v1":
			v1 = valor
		}
	}
	segundos, err := strconv.ParseInt(t, 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-segundos)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, segredo)
	mac.Write([]byte(t + "."))
	mac.Write(corpoBruto)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1))
}

O segredo é o texto inteiro, com o prefixo whsec_.

Testar no simulado

Os webhooks saem também no ambiente simulado. Para receber no seu computador durante o desenvolvimento, exponha a porta local com um túnel https (como o de ferramentas do tipo ngrok ou Cloudflare Tunnel) e cadastre essa URL. Endereços locais e de rede privada são recusados.