Webhooks

Eventos, entrega, novas tentativas e como validar a assinatura.

Webhooks avisam o seu sistema quando algo acontece, sem você precisar perguntar. Cadastre o endereço no portal, em Webhooks, escolha os eventos e o ambiente, e guarde o segredo (whsec_…). Se precisar dele de novo, use Ver segredo no menu do endereço.

Eventos

EventoQuandoAmbiente
consulta.concluidaConsulta concluída com resultado (qualquer código exceto os inconclusivos).Teste e produção
consulta.inconclusivaConsulta terminou sem o resultado pedido. O campo cobrada diz se entrou na fatura.Teste e produção
chave.criadaAlguém criou uma chave de API na conta.O da chave
chave.revogadaUma chave de API foi revogada.O da chave
chave.limiteA chave passou de 80% do limite de gasto do dia.O da chave
saldo.baixoO saldo pré-pago ficou abaixo do aviso configurado.Produção
saldo.recarregadoEntrou crédito na conta (PIX pago ou lançamento).Produção
fatura.fechadaA fatura do mês fechou.Produção
assinatura.assinadaUma pessoa assinou o documento. Chega uma vez por pessoa.O da chave
assinatura.concluidaTodos assinaram: o PDF assinado já pode ser baixado.O da chave
assinatura.recusadaUma pessoa recusou assinar. O documento é encerrado.O da chave
assinatura.canceladaO documento foi cancelado antes de todos assinarem.O da chave
assinatura.expiradaO prazo acabou sem que todos assinassem.O da chave

O webhook de consulta leva o desfecho, não o detalhe. A consulta que entra na fila dispara consulta.inconclusiva com em_processamento e, quando termina, um segundo evento com o desfecho final. Para os itens, os dados e a certidão — típico de consulta que passou pela fila de reprocessamento (em_processamento) —, busque a consulta pelo id com GET /v1/{produto}/consultas/{id}, com a mesma chave. Não cobra; o detalhe fica disponível por 24 horas.

Como a entrega funciona

Cada evento é um POST para o seu endereço (HTTPS obrigatório) com este corpo:

{
  "evento": "consulta.concluida",
  "em": "2026-09-16T13:02:11Z",
  "dados": {
    "id": "req_01J9Z3K8W4M2Q7T5V6X8Y9A0BC",
    "produto": "antecedentes",
    "pessoa": "000.000.001-91",
    "referencia": "cadastro-4821",
    "resultado": "Nada consta",
    "codigo": "nada_consta",
    "cobrada": true,
    "custo": "0.60"
  }
}

Os eventos de conta trazem em dados: chave.* → chave (mascarada) e nome, e chave.limite também gastoHoje e limiteDia; saldo.baixo → saldo; saldo.recarregado → valor; fatura.fechada → numero, competencia (AAAA-MM), total e vencimento (AAAA-MM-DD). Valores em dinheiro vêm como texto com ponto decimal.

Os eventos de assinatura trazem em dados: id (o documento), titulo, referencia (a sua, quando enviada) e estado; assinatura.assinada traz também signatario, com nome, email e assinouEm.

CabeçalhoConteúdo
Content-Typeapplication/json
User-AgentNexusQuery-Webhook/1
X-NexusQuery-EventoO nome do evento.
X-NexusQuery-Assinaturasha256= + HMAC-SHA256 do corpo cru, com o seu segredo, em hexadecimal.
  • Responda 2xx em até 10 segundos. Qualquer outro status, redirecionamento ou falta de resposta conta como falha.
  • Tentativas: até 5 no total — a primeira e mais 4, depois de 1, 5, 15 e 60 minutos. O histórico de entregas fica no portal.
  • Pode chegar repetido ou fora de ordem. Use dados.id (consultas) para ignorar o que já processou.
  • Processe depois de responder. Responda 200 assim que validar a assinatura e trate o evento em segundo plano.

Validar a assinatura

Calcule o HMAC sobre os bytes exatos que chegaram — antes de converter o JSON — e compare em tempo constante. Assinatura errada: responda 401 e descarte.

// Node.js (Express): use express.raw para ter o corpo cru
import crypto from "node:crypto";

// O segredo do HMAC são os bytes do hexadecimal depois de "whsec_".
const segredoEmBytes = Buffer.from(process.env.NEXUSQUERY_WEBHOOK_SEGREDO.replace(/^whsec_/, ""), "hex");

app.post("/webhooks/nexusquery", express.raw({ type: "application/json" }), (req, res) => {
  const esperado = "sha256=" + crypto.createHmac("sha256", segredoEmBytes).update(req.body).digest("hex");
  const recebido = req.get("X-NexusQuery-Assinatura") ?? "";
  const ok = recebido.length === esperado.length && crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200);
  processarDepois(JSON.parse(req.body));
});
# Python
import hashlib, hmac

# segredo = bytes.fromhex(os.environ["NEXUSQUERY_WEBHOOK_SEGREDO"].removeprefix("whsec_"))
def assinatura_valida(corpo: bytes, recebido: str, segredo: bytes) -> bool:
    esperado = "sha256=" + hmac.new(segredo, corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, recebido)
// Go — segredo, _ := hex.DecodeString(strings.TrimPrefix(os.Getenv("NEXUSQUERY_WEBHOOK_SEGREDO"), "whsec_"))
func assinaturaValida(corpo []byte, recebido string, segredo []byte) bool {
	m := hmac.New(sha256.New, segredo)
	m.Write(corpo)
	esperado := "sha256=" + hex.EncodeToString(m.Sum(nil))
	return hmac.Equal([]byte(esperado), []byte(recebido))
}

O segredo usado no HMAC são os bytes do valor hexadecimal depois de whsec_. Exemplo: para whsec_9f86d0…, decodifique 9f86d0… de hexadecimal para bytes e use esses bytes como chave.