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.
Every delivery includes X-Intellectua-Signature to verify origin authenticity.
Automatic 3-attempt backoff (1s, 2s) with 10s request timeout and in-app alerts on delivery failure.
Includes ephemeral 24-hour signed fileUrl links for immediate PDF downloads.
Supported Event Types
All document state transitions and pipeline milestones emitted by Intellectua.
document.receivedIngestionTriggered whenever a new document or fax is received via eFax, secure email alias, direct upload, or the v1 REST API.
document.ocr_completedAI PipelineTriggered when AI Optical Character Recognition and structured clinical data extraction finishes.
document.classifiedClassificationTriggered when document type categorization (e.g. Lab Report, Referral, Order) and team routing are established.
document.signature_requestedClinical WorkflowTriggered when AI identifies an action requirement requiring attending physician countersignature or approval.
document.signedE-SignatureTriggered upon digital signature completion (single sign or Sign & Return fax dispatch).
document.filed_ehrEHR FilingTriggered when a document is assigned to a patient chart or archived into the healthcare EHR repository.
document.failedExceptionsTriggered upon carrier transmission failure, unrecoverable AI processing exception, or document rejection.
document_version.createdVersioningTriggered 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:
{
"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
| Field | Type | Description |
|---|---|---|
| id | string | Unique event delivery identifier (e.g. evt_...). |
| event | string | The name of the triggered event (e.g. document.received). |
| data.fileUrl | string | Direct ephemeral 24-hour signed download URL on intellectua.ai. Streams decrypted PDF directly. |
| data.apiUrl | string | Permanent REST API download endpoint requiring standard Authorization: Bearer <apiKey>. |
| data.location | object | null | Clinic branch or healthcare facility metadata. |
| data.sender | object | Sender contact info (name, organization, fax number, phone, email). |
| data.patient | object | null | Matched or AI-extracted patient demographics (Name, DOB, MRN, Gender). |
| data.latestVersion | object | The most recent file version with size, sha256 hash, and signed fileUrl. |
| data.versions | array | Full 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):
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");
});