Guías · 05

Webhooks firmados

Recibe notificaciones en tiempo real y verifica la firma HMAC.

Los webhooks te avisan en tiempo real cuando un documento cambia de estado, sin necesidad de consultar la API. Crea un endpoint indicando la URL a la que llamar y los eventos que te interesan.

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

Al crearlo recibes un secret (con prefijo whsec_) mostrado una sola vez: sirve para verificar la firma de cada entrega. Consérvalo de forma segura, no podrás volver a verlo.

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

Eventos disponibles

document.processed — extracción completada
document.review_needed — hace falta una verificación humana
document.failed — procesamiento fallido

El payload

Cada entrega es un POST JSON con dos headers clave: X-IDP-Event con el nombre del evento y X-IDP-Signature con la firma HMAC SHA-256 del cuerpo de la solicitud.

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

Verificar la firma

Calcula el HMAC SHA-256 del cuerpo en bruto de la solicitud usando tu secret y compáralo, en tiempo constante, con el header X-IDP-Signature. Responde con un código 2xx para confirmar la recepción: de lo contrario LOCRAI reintenta con backoff progresivo.

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

¿Listo para integrar LOCRAI?

Genera una clave API desde el panel y empieza, o escríbenos: te ayudamos a conectar LOCRAI con tus sistemas, también con conectores a medida.

Contáctanos