Webhooks

Em vez de perguntar de tempos em tempos se a consulta ficou pronta, você registra uma URL sua e a ZapCar avisa quando o evento acontece. É o caminho recomendado para volumes maiores e para o CRLV e a ATPV-e, que podem levar minutos: economiza requisições e chega antes.

Configurar um endpoint

1. 1

   Passo 1: Cadastre a URL

   No Portal do Cliente, em Conta › Integrações, aba Webhooks. A URL precisa ser HTTPS e pública: endereços de rede interna (localhost, 10.x, 192.168.x, 169.254.x…) são recusados no cadastro e de novo antes de cada entrega.
2. 2

   Passo 2: Escolha os eventos

   Marque só o que o seu sistema trata. Sem nenhum marcado, o endpoint recebe todos.
3. 3

   Passo 3: Guarde o secret

   A resposta do cadastro traz o secret (whsec_…) uma única vez. É com ele que você valida cada entrega. Dá para rotacionar o secret a qualquer momento: o antigo deixa de valer na hora.
4. 4

   Passo 4: Teste

   O botão Testar envia um webhook.test pelo mesmo caminho dos eventos reais (assinatura, timeout e reentrega), sem custo. O histórico de entregas mostra status, código HTTP e erro de cada uma.

Eventos

O que chega no seu endpoint

Um POST com corpo JSON e estes cabeçalhos:

{
  "id": "b2c3d4e5-6f70-...",       // id do EVENTO: use para idempotência
  "type": "query.completed",
  "created_at": "2026-08-19T12:00:00.000Z",
  "data": {
    "id": "a1b2c3d4-...",          // id da consulta (GET /v1/consultas/:id)
    "servico": "CONSULTA_COMPLETA", // código INTERNO do serviço (não é o slug da API)
    "status": "CONCLUIDO"           // status INTERNO gravado na consulta
  }
}

data.servico e data.status usam os nomes internos

data.servico é o código interno do serviço, diferente do slug que você manda no POST, e data.status é o status gravado na consulta, não o processando/concluido/erro do GET. Para decidir, use o type do evento e leia o resultado em GET /v1/consultas/{id}, que responde com o slug e o status públicos.

Em query.completed, data.status vem CONCLUIDO (ou PAGO na Consulta Simples). Em query.failed, vem o status de falha gravado (ex.: ERRO, ERRO_CONSULTA, ERRO_EMISSAO). Não programe contra esses valores: eles descrevem o armazenamento interno e podem ganhar variações. O contrato estável é o type.

Validar a assinatura

O cabeçalho X-ZapCar-Signature traz t (timestamp Unix, em segundos) e v1 (HMAC-SHA256 em hexadecimal). Para validar: calcule o HMAC-SHA256 de <t>.<corpo bruto> com o seu secret, compare com v1 em tempo constante e recuse timestamps com mais de 5 minutos de diferença (proteção contra replay).

const crypto = require("crypto");

// Corpo BRUTO (Buffer), não req.body já parseado: a assinatura é sobre os bytes.
app.post("/webhooks/zapcar", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-ZapCar-Signature") || "";
  const t  = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([a-f0-9]+)/.exec(header)?.[1];
  if (!t || !v1) return res.sendStatus(400);

  // Rejeita evento antigo: barra o replay de uma entrega capturada.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

  const esperado = crypto
    .createHmac("sha256", process.env.ZAPCAR_WEBHOOK_SECRET)
    .update(t + "." + req.body.toString("utf8"))
    .digest("hex");

  // Comparação em tempo constante.
  const a = Buffer.from(esperado), b = Buffer.from(v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const evento = JSON.parse(req.body.toString("utf8"));

  // Responda 2xx RÁPIDO e processe depois (fila). Demorar aqui vira retry nosso.
  res.sendStatus(200);
  processarDepois(evento); // ignore se evento.id já foi processado
});

Reentrega, ordem e duplicatas

Quando o seu endpoint fica fora do ar

Esgotadas as tentativas, a entrega fica marcada como falha no histórico do portal e não é reenviada depois. O resultado da consulta não se perde: ele continua em GET /v1/consultas/{id}. Por isso, mantenha uma reconciliação: de tempos em tempos, consulte os id que você criou e ainda não viu concluir. Webhook é o caminho rápido; a reconciliação é a rede de segurança.

Simulador de payload

Gere um evento assinado com o mesmo algoritmo do backend e dispare contra o seu ambiente de desenvolvimento, ou cole uma entrega recebida para conferir a assinatura. Tudo é calculado neste navegador; nada é enviado à ZapCar. Para o teste ponta a ponta, use o Testar do portal.