Guide · 05

Webhook firmati

Ricevi notifiche in tempo reale e verifica la firma HMAC.

I webhook ti avvisano in tempo reale quando un documento cambia stato, senza bisogno di interrogare l'API. Crea un endpoint indicando l'URL da chiamare e gli eventi che ti interessano.

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"]
  }'

Alla creazione ricevi un secret (con prefisso whsec_) mostrato una sola volta: serve a verificare la firma di ogni consegna. Conservalo in modo sicuro, non potrai rivederlo.

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"
}

Eventi disponibili

document.processed — estrazione completata
document.review_needed — serve una verifica umana
document.failed — elaborazione non riuscita

Il payload

Ogni consegna è una POST JSON con due header chiave: X-IDP-Event con il nome dell'evento e X-IDP-Signature con la firma HMAC SHA-256 del corpo della richiesta.

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"
}

Verificare la firma

Calcola l'HMAC SHA-256 del corpo grezzo della richiesta usando il tuo secret e confrontalo, a tempo costante, con l'header X-IDP-Signature. Rispondi con un codice 2xx per confermare la ricezione: in caso contrario LOCRAI riprova con backoff progressivo.

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();
});

Pronto a integrare LOCRAI?

Genera una chiave API dalla dashboard e inizia, oppure scrivici: ti aiutiamo a collegare LOCRAI ai tuoi sistemi, anche con connettori su misura.

Contattaci