Webhooks · Documentación API Nexcar

¿Cómo funcionan?#

Cuando un documento o caso avanza en su procesamiento (clasificación, OCR, extracción de datos, validación), Nexcar envía una solicitud HTTP POST a la URL que hayas configurado, con un payload JSON describiendo el evento.

Configura tu URL receptora con tu contacto en Nexcar.

Eventos disponibles#

Evento	Cuándo se dispara
`document.classified`	Se asignó (o reasignó) el tipo de un documento
`document.ready`	El OCR del documento terminó y los datos están disponibles
`document.validity`	La extracción de vigencia/códigos terminó
`case.upload.completed`	Terminó la carga inicial de archivos al crear el caso
`case.status.changed`	El estado del caso cambió

Estructura del payload#

Todos los eventos comparten el mismo envelope:

{
  "event": "document.ready",
  "occurred_at": "2026-04-09T23:04:18.515738Z",
  "data": {
    "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
    "document_id": "abc123",
    "type": "factura",
    "parsed_data": {
      "vin": "3VWFE21C04M000001",
      "monto_total": 285000
    }
  }
}

Verificación#

Cada solicitud incluye el encabezado x-nexcar-signature con un HMAC SHA-256 calculado sobre el body usando el secreto del webhook que te compartimos. Verifícalo así (Node.js):

const crypto = require("crypto");

function verify(req, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(req.headers["x-nexcar-signature"])
  );
}

Reintentos#

Si tu endpoint responde con un código >= 400 o no responde en menos de 10 segundos, reintentamos con backoff exponencial hasta 5 veces a lo largo de 24 horas. Después de eso el evento se descarta y queda registrado en tu bitácora.

Responde lo antes posible con 2xx y procesa el evento de forma asíncrona en tu lado.

Idempotencia#

Cada evento incluye un identificador único en data.event_id. Tu sistema debe ignorar eventos repetidos en caso de reintento.