Webhooks · Nexcar API Docs

How they work#

When a document or case advances through processing (classification, OCR, data extraction, validation), Nexcar sends an HTTP POST to the URL you configured, with a JSON payload describing the event.

Configure your receiving URL with your Nexcar contact.

Available events#

Event	When it fires
`document.classified`	A document type was set (or changed)
`document.ready`	The document's OCR finished and the data is available
`document.validity`	Validity / code extraction finished
`case.upload.completed`	The initial upload of files for a case finished
`case.status.changed`	The case state changed

Payload structure#

Every event shares the same 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
    }
  }
}

Verification#

Each request includes the x-nexcar-signature header with an HMAC SHA-256 computed over the raw body using the webhook secret we share with you. Verify it like this (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"])
  );
}

Retries#

If your endpoint replies with >= 400 or doesn't respond within 10 seconds, we retry with exponential backoff up to 5 times across 24 hours. After that the event is dropped and recorded in your audit log.

Reply with 2xx as fast as possible and process the event asynchronously on your side.

Idempotency#

Every event includes a unique identifier in data.event_id. Your system must ignore repeat events in case of retries.