Webhooks

Receive real-time notifications when events occur.

Webhook Events

Event	Description
extraction.completed	AI extraction finished successfully
extraction.failed	AI extraction failed
shipment.validated	Shipment validation completed
document.generated	Document PDF generated
document.failed	Document generation failed

Webhook Payload

{
  "event": "document.generated",
  "timestamp": "2026-03-31T10:00:05Z",
  "data": {
    "job_id": "job_doc_a1b2c3d4",
    "shipment_id": "shp_a1b2c3d4",
    "document_type": "COMMERCIAL_INVOICE",
    "status": "completed",
    "download_url": "https://...",
    "hash": "sha256:a1b2c3d4e5f6..."
  }
}

Webhook Signature

Each webhook request includes a X-Klervex-Signature header for verification:

X-Klervex-Signature: sha256=a1b2c3d4...
X-Klervex-Timestamp: 1711872000

Verify by computing HMAC-SHA256 of the raw request body with your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Configuration

Configure webhooks in Settings > Webhooks in the Klervex dashboard. Each webhook subscription specifies:

• URL — The endpoint to receive events
• Events — Which events to subscribe to
• Secret — For signature verification