n8n

Create the credentialCopy Anchor Link

In Credentials → Add credential → Header Auth:

Name it, for example, Constaia (test). For production create another one with the ck_live_… key and switch the node's credential once the workflow is tested.

Configure the HTTP Request nodeCopy Anchor Link

Under Body Parameters add two parameters:

A typical value for options:

{
  "expect": ["es_dni", "es_nie", "passport"],
  "checks": { "min_age_years": 18 },
  "language": "en",
  "metadata": { "source": "n8n" }
}

You can use expressions inside the JSON, for example to check the holder against form data: "holder": { "full_name": "{{ $json.name }}" } inside checks. All options are in POST /v1/analyze and the checks in Checks.

Route by verdictCopy Anchor Link

Add a Switch node (Rules mode) with the value {{ $json.verdict.status }} and three String → is equal to rules: valid, invalid and review. If you only need two outputs, an IF node with the same expression and the condition is equal to valid is enough.

Each extracted field is an object: the value is in {{ $json.fields.document_number.value }} and the confidence in {{ $json.fields.document_number.confidence }}. What each status means is in Verdicts.

Handle errorsCopy Anchor Link

If the API responds with an error (401, 402, 413, 422, 429…), the node fails. In Settings → On Error choose Continue (using error output) to send those cases to their own branch. The error body follows the format { "error": { "type", "code", "message", "param", "request_id" } }; keep request_id if you need support. The codes are in Errors.

Also account for the 202 response: if the analysis does not finish within 30 s (long PDFs), the API returns the analysis with status: "queued" or "processing" and an empty verdict. Add a condition on {{ $json.status }} equal to completed before the Switch, or use async: true and receive the result by webhook (below).

Create the Webhook nodeCopy Anchor Link

Raw Body is essential: the signature is computed over the exact body, byte for byte, and the node exposes it as binary data (property data; check it in the node output). Responding immediately returns a fast 2xx; Constaia considers the delivery failed if it does not get a 2xx within 15 s.

Register the endpointCopy Anchor Link

Copy the node's Production URL (activate the workflow) and register it in the dashboard or through the API. The endpoint only receives events of the mode of the key you create it with.

curl https://api.constaia.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://n8n.example.com/webhook/constaia","events":["analysis.completed","analysis.failed","analysis.review_required"]}'

The response includes secret: "whsec_…" only this once. Store it.

Verify the signature in a Code nodeCopy Anchor Link

Add a Code node (JavaScript, Run Once for All Items) right after the Webhook:

const crypto = require("crypto");

const secret = $env.CONSTAIA_WEBHOOK_SECRET; // whsec_…
const headers = $input.first().json.headers;
const raw = await this.helpers.getBinaryDataBuffer(0, "data");

const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) throw new Error("Missing signature headers");

if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) throw new Error("Timestamp outside tolerance");

const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto
  .createHmac("sha256", key)
  .update(Buffer.concat([Buffer.from(`${id}.${timestamp}.`), raw]))
  .digest();

const valid = signatures.split(" ").some((entry) => {
  const [version, signature] = entry.split(",");
  if (version !== "v1" || !signature) return false;
  const received = Buffer.from(signature, "base64");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
if (!valid) throw new Error("Invalid signature");

const event = JSON.parse(raw.toString("utf8"));
return [{ json: { webhook_id: id, ...event } }];

If the signature is not valid, the node throws and the execution stops: nothing after it is processed. Next, a Switch on {{ $json.type }} separates analysis.completed, analysis.review_required, analysis.failed and batch.completed; the analysis is in {{ $json.data }}.

Drop duplicatesCopy Anchor Link

Constaia retries failed deliveries for about 3 days, always with the same webhook-id. Store the processed webhook_id values (in your database, or with the Remove Duplicates node in Remove Items Processed in Previous Executions mode if your version has it) and drop repeats.