Guides · 05

Signed webhooks

Receive real-time notifications and verify the HMAC signature.

Webhooks notify you in real time when a document changes state, without needing to poll the API. Create an endpoint by indicating the URL to call and the events you're interested in.

POST /webhooksbash

curl -X POST https://app.locrai.com/api/v1/webhooks \
  -H "Authorization: Bearer idp_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Endpoint produzione",
    "url": "https://example.com/webhooks/locrai",
    "events": ["document.processed", "document.review_needed", "document.failed"]
  }'

On creation you receive a secret (with the whsec_ prefix) shown only once: it's used to verify the signature of every delivery. Store it securely, you won't be able to see it again.

201 Created — il secret è mostrato una sola voltajson

{
  "data": {
    "id": "5d7c...",
    "name": "Endpoint produzione",
    "url": "https://example.com/webhooks/locrai",
    "events": ["document.processed", "document.review_needed", "document.failed"],
    "active": true
  },
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Available events

document.processed — extraction completed
document.review_needed — human review required
document.failed — processing failed

The payload

Every delivery is a JSON POST with two key headers: X-IDP-Event with the event name and X-IDP-Signature with the HMAC SHA-256 signature of the request body.

POST verso il tuo endpointjson

// Headers
// X-IDP-Event: document.processed
// X-IDP-Signature: sha256=<hmac-hex>

{
  "event": "document.processed",
  "document": {
    "id": "9b1f0e2c-1c2d-4f5a-8e9b-0a1b2c3d4e5f",
    "original_name": "fattura-2026-123.pdf",
    "status": "extracted",
    "extraction_path": "text",
    "confidence": 0.93,
    "extracted_data": { "invoice_number": "2026/123", "total": 1220.0 }
  },
  "timestamp": "2026-06-25T10:00:00+00:00"
}

Verifying the signature

Compute the HMAC SHA-256 of the raw request body using your secret and compare it, in constant time, with the X-IDP-Signature header. Respond with a 2xx code to confirm receipt: otherwise LOCRAI retries with progressive backoff.

Verifica della firma (Node.js / Express)javascript

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  // confronto a tempo costante
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader ?? ""),
    Buffer.from(expected)
  );
}

app.post("/webhooks/locrai", express.raw({ type: "*/*" }), (req, res) => {
  const ok = isValid(
    req.body,
    req.header("X-IDP-Signature"),
    process.env.LOCRAI_WEBHOOK_SECRET
  );
  if (!ok) return res.status(400).end();

  const { event, document } = JSON.parse(req.body.toString());
  // gestisci event + document.extracted_data ...
  res.status(200).end();
});

Ready to integrate LOCRAI?

Generate an API key from the dashboard and get started, or write to us: we'll help you connect LOCRAI to your systems, including custom connectors.