API Reference

Webhooks & Events

Subscribe to real-time, HMAC-SHA256 signed webhook notifications on intellectua.ai. Includes rich document metadata, patient demographics, clinical tags, and direct signed PDF download links.

HMAC-SHA256 Signed

Every delivery includes X-Intellectua-Signature to verify origin authenticity.

Exponential Retries

Automatic 3-attempt backoff (1s, 2s) with 10s request timeout and in-app alerts on delivery failure.

Direct Decrypted URLs

Includes ephemeral 24-hour signed fileUrl links for immediate PDF downloads.

Supported Event Types

All document state transitions and pipeline milestones emitted by Intellectua.

8 Events
document.receivedIngestion

Triggered whenever a new document or fax is received via eFax, secure email alias, direct upload, or the v1 REST API.

document.ocr_completedAI Pipeline

Triggered when AI Optical Character Recognition and structured clinical data extraction finishes.

document.classifiedClassification

Triggered when document type categorization (e.g. Lab Report, Referral, Order) and team routing are established.

document.signature_requestedClinical Workflow

Triggered when AI identifies an action requirement requiring attending physician countersignature or approval.

document.signedE-Signature

Triggered upon digital signature completion (single sign or Sign & Return fax dispatch).

document.filed_ehrEHR Filing

Triggered when a document is assigned to a patient chart or archived into the healthcare EHR repository.

document.failedExceptions

Triggered upon carrier transmission failure, unrecoverable AI processing exception, or document rejection.

document_version.createdVersioning

Triggered whenever a new document version (signed copy, annotation, or redacted file) is generated.

Common Payload Schema

Every webhook event contains a standardized top-level envelope with comprehensive document, patient, location, sender, and file version details:

Standard Webhook Envelope (JSON)application/json
{
  "id": "evt_9c18df567e9140a28f11",
  "event": "document.received",
  "timestamp": "2026-09-29T22:30:00.000Z",
  "organizationId": "org_default_clinic",
  "data": {
    "id": "doc_8f12a39bc4e0",
    "documentStatus": "RECEIVED",
    "direction": "INBOUND",
    "mode": "SINCH",
    "priority": "ROUTINE",
    "pageCount": 3,
    "fileUrl": "https://app.intellectua.ai/api/documents/doc_8f12a39bc4e0/file?token=eyJkb2NJZCI6ImRvY184ZjEyYSIsImV4cCI6MTc5...",
    "apiUrl": "https://api.intellectua.ai/v1/documents/doc_8f12a39bc4e0/download",
    "receivedAt": "2026-09-29T22:30:00.000Z",
    "processedAt": null,
    "completedAt": null,
    "location": {
      "id": "loc_nyc_01",
      "name": "Manhattan Medical Center"
    },
    "sender": {
      "source": "+15552345678",
      "contactId": "cnt_3a91bf20",
      "name": "Dr. Meredith Grey",
      "organization": "Seattle Grace Hospital",
      "faxNumber": "+15552345678",
      "phone": "+15559876543",
      "email": "[email protected]"
    },
    "recipient": {
      "destination": "+15551234567"
    },
    "patient": {
      "id": "pat_91823ab",
      "name": "Jane Doe",
      "dob": "1985-04-12",
      "mrn": "MRN-10293",
      "gender": "FEMALE"
    },
    "labels": [
      {
        "id": "lbl_ref",
        "name": "Referral",
        "code": "REF",
        "color": "#6366f1"
      }
    ],
    "latestVersion": {
      "id": "ver_01",
      "versionNumber": 1,
      "fileSizeBytes": 204850,
      "mimeType": "application/pdf",
      "sha256Hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "isOriginal": true,
      "fileUrl": "https://app.intellectua.ai/api/documents/doc_8f12a39bc4e0/file?version=1&token=eyJkb2NJZCI6ImRvY184ZjEyYSIsInZlciI6MSwiZXhwIjoxNzk...",
      "apiUrl": "https://api.intellectua.ai/v1/documents/doc_8f12a39bc4e0/download?version=1",
      "createdAt": "2026-09-29T22:30:00.000Z"
    },
    "versions": [
      {
        "id": "ver_01",
        "versionNumber": 1,
        "fileSizeBytes": 204850,
        "mimeType": "application/pdf",
        "sha256Hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "isOriginal": true,
        "fileUrl": "https://app.intellectua.ai/api/documents/doc_8f12a39bc4e0/file?version=1&token=eyJkb2NJZCI6ImRvY184ZjEyYSIsInZlciI6MSwiZXhwIjoxNzk...",
        "apiUrl": "https://api.intellectua.ai/v1/documents/doc_8f12a39bc4e0/download?version=1",
        "createdAt": "2026-09-29T22:30:00.000Z"
      }
    ]
  }
}

Payload Field Reference

FieldTypeDescription
idstringUnique event delivery identifier (e.g. evt_...).
eventstringThe name of the triggered event (e.g. document.received).
data.fileUrlstringDirect ephemeral 24-hour signed download URL on intellectua.ai. Streams decrypted PDF directly.
data.apiUrlstringPermanent REST API download endpoint requiring standard Authorization: Bearer <apiKey>.
data.locationobject | nullClinic branch or healthcare facility metadata.
data.senderobjectSender contact info (name, organization, fax number, phone, email).
data.patientobject | nullMatched or AI-extracted patient demographics (Name, DOB, MRN, Gender).
data.latestVersionobjectThe most recent file version with size, sha256 hash, and signed fileUrl.
data.versionsarrayFull historical versions list with individual signed download links.

HMAC-SHA256 Signature Verification

Every webhook request includes an X-Intellectua-Signature header containing an HMAC-SHA256 hex signature computed using your organization signing secret (configured under Settings → Webhooks):

Node.js / Express VerificationJavaScript
const crypto = require("crypto");

// secret configured in Settings > Webhooks (starts with "intel_whsec_...")
function verifyWebhookSignature(payloadBuffer, headerSignature, webhookSecret) {
  const computed = crypto
    .createHmac("sha256", webhookSecret)
    .update(payloadBuffer)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(headerSignature)
  );
}

// In your Express router:
app.post("/webhooks/intellectua", (req, res) => {
  const signature = req.headers["x-intellectua-signature"];
  const isValid = verifyWebhookSignature(req.rawBody, signature, process.env.INTELLECTUA_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  console.log(`Received ${event} for document ${data.id}`);
  console.log(`Download PDF: ${data.fileUrl}`);

  res.status(200).send("OK");
});