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
| Evento | Quando | Ambiente |
|---|---|---|
consulta.concluida | Consulta concluída com resultado (qualquer código exceto os inconclusivos). | Teste e produção |
consulta.inconclusiva | Consulta terminou sem o resultado pedido. O campo cobrada diz se entrou na fatura. | Teste e produção |
chave.criada | Alguém criou uma chave de API na conta. | O da chave |
chave.revogada | Uma chave de API foi revogada. | O da chave |
chave.limite | A chave passou de 80% do limite de gasto do dia. | O da chave |
saldo.baixo | O saldo pré-pago ficou abaixo do aviso configurado. | Produção |
saldo.recarregado | Entrou crédito na conta (PIX pago ou lançamento). | Produção |
fatura.fechada | A fatura do mês fechou. | Produção |
assinatura.assinada | Uma pessoa assinou o documento. Chega uma vez por pessoa. | O da chave |
assinatura.concluida | Todos assinaram: o PDF assinado já pode ser baixado. | O da chave |
assinatura.recusada | Uma pessoa recusou assinar. O documento é encerrado. | O da chave |
assinatura.cancelada | O documento foi cancelado antes de todos assinarem. | O da chave |
assinatura.expirada | O 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çalho | Conteúdo |
|---|---|
Content-Type | application/json |
User-Agent | NexusQuery-Webhook/1 |
X-NexusQuery-Evento | O nome do evento. |
X-NexusQuery-Assinatura | sha256= + HMAC-SHA256 do corpo cru, com o seu segredo, em hexadecimal. |
- Responda
2xxem 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
200assim 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.