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
| Evento | Quando |
|---|---|
documento.autorizado | A nota foi autorizada. O XML e o PDF já estão disponíveis. |
documento.rejeitado | A SEFAZ (ou o Sistema Nacional) rejeitou a nota. Veja codigo_sefaz, motivo_sefaz e rejeicao. O número continua reservado. |
documento.denegado | Uso 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.contingencia | NFC-e emitida em contingência offline; o cupom pode ser entregue e será transmitido quando a SEFAZ voltar. |
documento.cancelado | O cancelamento (ou a substituição da NFS-e) foi registrado. |
evento.registrado | Um evento da nota (cancelamento, carta de correção) foi registrado. |
evento.rejeitado | A SEFAZ recusou o evento; a nota continua como estava. |
inutilizacao.concluida | A faixa de números foi inutilizada. |
certificado.vencendo | O 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:
Motor-Evento: o tipo do evento.Motor-Evento-Id: o identificador do evento, o mesmo em todas as tentativas.Motor-Assinatura:t=<unix>,v1=<hex>, em quev1é o HMAC-SHA256, com o segredo, de<t>.<corpo>.
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:
- Responda logo e processe depois (numa fila do seu lado).
- A mesma entrega pode chegar mais de uma vez: guarde o
Motor-Evento-Ide ignore o que já processou. - A ordem de chegada não é garantida. Na dúvida, consulte o documento.
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.