Webhooks

TruEnroll pushes events to your registered HTTPS endpoint as processing progresses. Classification, extraction, forensics, and translation emit completed or failed events. Operator-run evaluation emits a best-effort completion event; keep JSON polling as a fallback for evaluation progress.

Registering a webhook endpoint

curl -X POST https://api.truenroll.com/partner/v1/webhook-config \
  -H "x-api-key: $TRUENROLL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/truenroll/webhook",
    "apiKey": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "audience": "partner"
  }'

Set audience to partner so the endpoint receives Partner API case events; internal platform events are never mixed into partner delivery. See Configuring webhooks for the full request and field reference.

Authenticating webhook requests

When you register your endpoint, you supply a secret key (the apiKey). TruEnroll includes that key as an x-api-key header on every webhook request it sends to you. Verify it on each request and reject anything that doesn’t match:

if (req.get('x-api-key') !== process.env.TRUENROLL_WEBHOOK_KEY) {
  return res.sendStatus(401);
}

Always verify the x-api-key header before acting on a webhook. Treat the key like a password (store it in a secret manager, never in source control) and serve your endpoint over HTTPS so the header is never sent in clear text.

Event names

Event	Fired when
`case.classification.completed`	Document classification succeeded
`case.classification.failed`	Document classification failed (terminal)
`case.extraction.completed`	Extraction succeeded; structured data is ready
`case.extraction.failed`	Extraction failed (terminal)
`case.forensics.completed`	Forensics analysis succeeded
`case.forensics.failed`	Forensics analysis failed (terminal)
`case.translation.completed`	Translation succeeded; output is ready
`case.translation.failed`	Translation failed (terminal)
`case.evaluation.completed`	All required case evaluations have completed; combined reports may still be processing

Upload feature events follow what actually runs on your uploads. A feature you did not request does not run, so you get no events for it, unless an operator starts it later in TruEnroll. Then its events arrive like any other. Uploads an operator added to the case in TruEnroll send no events.Evaluation completion is separate: it follows operator evaluation and is not selected through the upload’s features array. It fires for cases you created or linked. There is no case.evaluation.failed event.

Event payload

All events share the same envelope. Event-specific fields are carried inside data alongside the common fields:

{
  "eventName": "case.extraction.completed",
  "data": {
    "caseId": "6850abc123def456abc78901",
    "externalId": "applicant-9876",
    "uploadId": "6850def456abc789abc12301",
    "credentialId": "6850abc789abc123def45601",
    "occurredAt": "2025-06-22T10:30:00Z"
  }
}

string

The event name from the table above. Use this to route incoming events in your handler.

string

TruEnroll’s case ID, the same id the case endpoints return. Use this to call the result endpoint.

string

The externalId you provided when creating or linking the case.

string

The upload within the case that this event relates to. Absent on the case-level case.evaluation.completed event.

string (ISO 8601)

The timestamp when the processing event occurred internally.

string

Present on extraction, forensics, and translation events. Identifies the credential the result belongs to.

string

Present on forensics and translation events. Identifies the source file the result was produced from.

Depending on the event, data may carry additional fields. For example, credentialIds (the credentials classification produced) appears on case.classification.completed, and an error string on *.failed events. Treat data as an open object and read only the fields you need.

Evaluation completion payload

Evaluation completion spans the case’s uploads. Its payload carries IDs so you can call the evaluation JSON endpoint for the current results. It contains no uploadId, credentialId, or fileId.

{
  "eventName": "case.evaluation.completed",
  "data": {
    "caseId": "6712abcdef123456abcdef01",
    "externalId": "applicant-9876",
    "caseNumber": 10482,
    "credentialIds": ["6712abcdef123456abcdef02"],
    "evaluationIds": ["6712abcdef123456abcdef04"],
    "completedAt": "2026-09-14T11:22:05.000Z",
    "occurredAt": "2026-09-14T11:22:06.120Z"
  }
}

caseId is the case ID. caseNumber is the numeric report reference, or null. credentialIds and evaluationIds identify the completed credentials and rows. completedAt identifies the completion timestamp; occurredAt is the webhook creation timestamp. externalId can be null if unavailable. An operator can reopen an evaluation or edit a document, then complete the case again. You can receive another completion event for the same case. Deduplicate evaluation notifications using eventName + data.caseId + data.completedAt so you accept later completions. Fetch current results before acting because an evaluation can be reopened after the event was created. This event does not guarantee combined report readiness.

Event ordering

Events for different features within the same case arrive independently and in any order. Forensics and extraction run in parallel, so case.forensics.completed may arrive before case.extraction.completed or vice versa. Do not assume ordering between events for different features. Handle each event on its own merits. Do not assume ordering between events, including events for the same feature. Make each event handler idempotent and use the result endpoints to read the current state.

Delivery & retries

TruEnroll considers a delivery successful when your endpoint returns a 2xx status. If the delivery fails (non-2xx, a timeout, or a connection error), TruEnroll retries up to 5 times before giving up. Each attempt has a 300-second timeout. Because deliveries can be retried, the same event may reach your endpoint more than once. Make your handler idempotent: processing the same event twice should produce the same outcome. For upload events, deduplicate on a stable key such as eventName + data.uploadId (+ data.credentialId or data.fileId where present). For evaluation events, use eventName + data.caseId + data.completedAt. Evaluation completion notifications are best-effort, with no at-least-once guarantee. A notification can be lost before it is queued for HTTP delivery. Once queued, the normal HTTP retries above apply. Keep polling GET /cases/{id}/evaluation as a fallback rather than waiting indefinitely for this event.

Handling events

A minimal webhook handler:

app.post('/truenroll/webhook', express.json(), async (req, res) => {
  // Verify the shared secret before trusting the request (see below)
  if (req.get('x-api-key') !== process.env.TRUENROLL_WEBHOOK_KEY) {
    return res.sendStatus(401);
  }

  // Acknowledge immediately; TruEnroll will retry if it doesn't get 2xx
  res.sendStatus(200);

  const { eventName, data } = req.body;

  switch (eventName) {
    case 'case.extraction.completed':
      await handleExtractionComplete(data.caseId, data.credentialId);
      break;
    case 'case.extraction.failed':
      await handleExtractionFailed(data.caseId, data.credentialId);
      break;
    case 'case.forensics.completed':
      await handleForensicsComplete(data.caseId, data.fileId);
      break;
    case 'case.evaluation.completed':
      await handleEvaluationComplete(data.caseId);
      break;
    // handle remaining events...
  }
});

Respond with 2xx before doing work. TruEnroll considers delivery successful when your endpoint returns a 2xx status. If your handler times out or throws before responding, TruEnroll will retry the delivery. Acknowledge first, then process asynchronously.

Classification suppression

If you submitted an upload with classify: false, TruEnroll will not emit case.classification.completed or case.classification.failed events for that upload.

What to do when a stage fails

A case.*.failed event means that stage is done and won’t be retried automatically. Other stages may still complete: You can still call the result endpoints for stages that succeeded. Use the overall case status (GET /cases/{id}) to determine whether to resubmit or flag for manual review.

Overview

Guides

API Reference

Registering a webhook endpoint

Authenticating webhook requests

Event names

Event payload

Evaluation completion payload

Event ordering

Delivery & retries

Handling events

Classification suppression

What to do when a stage fails

​Registering a webhook endpoint

​Authenticating webhook requests

​Event names

​Event payload

​Evaluation completion payload

​Event ordering

​Delivery & retries

​Handling events

​Classification suppression

​What to do when a stage fails

Registering a webhook endpoint

Authenticating webhook requests

Event names

Event payload

Evaluation completion payload

Event ordering

Delivery & retries

Handling events

Classification suppression

What to do when a stage fails