Skip to content
DevLab

Results in your backend

How results arrive in each mode, SDK and API together, SSE or polling, the pair to keep, one-off queries and the signed webhook of the deferred mode.

On this page
  1. How results arrive, by mode
  2. SDK and API, in both directions
  3. SSE or polling
  4. Engine sends no webhooks
  5. Keep the pair
  6. One-off queries
  7. The deferred webhook as a contract
  8. Test the webhook locally

On-device (real time): in the page, onResult and stop() → CaptureOutcome; at any time, GET /results/{userProtocolId}/{protocolMechanicId} or client.retrieveResults(userProtocolId, protocolMechanicId); while capturing, the event stream GET /stream/{userProtocolId}. Deferred (server-side): the processing service replays the recording against Engine and tells your backend with its signed webhook; then you read GET /results as above.

Backend first: createEngineAdmin creates the person and the enrolment, and the page captures with that pair. Browser first: the page captures with the SDK, and your backend reads later. Both rest on the same thing: your backend stores the pair at enrolment and, with it, reads GET /results whenever it needs to (createEngineAdmin().getResults is that route, from Node). This module stores the pair, reads the results and the stored interpretation, and deletes the person at the end; store is your database:

JavaScript
// Store and read later, from your backend. At enrolment, keep the pair next to your user: it is all you need to read
// the results later (a report, a dashboard, another session). Engine does not expire results today: they stay until
// you delete the person. `store` is your database; any table with these four columns will do.
import { randomUUID } from 'node:crypto'
import { createEngineAdmin } from '@neurologyca/capture-server'
/**
* @typedef {{ userId: string, externalId: string, userProtocolId: string, protocolMechanicId: string }} Capture
* @typedef {{ insert(c: Capture): Promise<string>, get(captureId: string): Promise<Capture | null>, ofUser(userId: string): Promise<Capture[]>, deleteOfUser(userId: string): Promise<void> }} CaptureStore
* @param {{ store: CaptureStore, engineBase?: string, apiKey?: string, fetch?: typeof fetch }} opts
*/
export function storeAndReadLater({ store, engineBase = process.env.ENGINE_BASE, apiKey = process.env.ENGINE_API_KEY, fetch: fetchImpl }) {
if (!engineBase || !apiKey) throw new Error('Set ENGINE_BASE and ENGINE_API_KEY in your backend environment')
const admin = createEngineAdmin({ baseUrl: engineBase, apiKey, fetch: fetchImpl })
/** @param {Capture} c */
const pairOf = (c) => ({ userProtocolId: c.userProtocolId, protocolMechanicId: c.protocolMechanicId })
return {
// 1 · At enrolment: create the person, enrol them and store the pair. The browser captures with that pair.
/** @param {string} userId your user @param {string} protocolId the protocol in your kit @param {string} [language] of the interpretation */
async enrolPerson(userId, protocolId, language = process.env.NARRATIVE_LANGUAGE ?? 'en') {
const externalId = randomUUID() // opaque: never the email
await admin.createUser({ externalId, name: 'person', narrative: { language } }) // without it, Engine writes in English
const { userProtocolId } = await admin.enrol(externalId, protocolId)
const next = await admin.getNextPosition(userProtocolId)
if (!next) throw new Error('The protocol has no position to capture')
const captureId = await store.insert({ userId, externalId, userProtocolId, protocolMechanicId: next.protocolMechanicId })
return { captureId, userProtocolId, protocolMechanicId: next.protocolMechanicId }
},
// 2 · Whenever you need it: now or weeks later. There is no webhook in real time: if you read right at the end and
// there is no data yet, read again a little later.
/** @param {string} captureId */
async readLater(captureId) {
const c = await store.get(captureId)
if (!c) return null
const { rawResults, aggResults, speech } = await admin.getResults(pairOf(c))
return { rawResults, aggResults, speech }
},
// The stored interpretation, with a protocol that interprets (Measurement does not). Without reAnalyze it is not
// generated or billed again: never ask for it in a loop. With inProgress: true (a 202: Engine is still writing it), it
// is not «no interpretation»: ask again after retryAfterMs (about 30 s when null), a few times at most.
/** @param {string} captureId */
async readInterpretation(captureId) {
const c = await store.get(captureId)
return c ? admin.analyze(pairOf(c)) : null
},
// 3 · When you are done: delete the person and everything of theirs in Engine. It cannot be undone.
/** @param {string} userId */
async forget(userId) {
for (const externalId of new Set((await store.ofUser(userId)).map((c) => c.externalId))) await admin.deleteUser(externalId)
await store.deleteOfUser(userId)
},
}
}

Since capture-server 0.15.0, getResults also returns speech: per step, what was asked (questionText) and what was said (transcript) (HCIs and results; only in the test environment’s Engine). speech is null when the Engine does not send the block. To read every mechanic of an enrolment at once, getProtocolResults({ userProtocolId }) returns { mechanics: [...] }, each with its protocolMechanicId, order, rawResults, aggResults and speech; it needs your key (a capture token cannot read it).

The raw call returns the same body (shortened to the aggregates):

JSON
{
"aggResults": {
"1": {
"mean": {
"valence": 6.751,
"arousal": 69.775,
"Confusion": 14.618,
"Stress_intens": 54.195
}
}
}
}

results.ready as the signal, /results as the truth. The event arrives once per position, and not in every case: keep polling GET /results until it has data.

JSON
{
"events": ["connected", "hci.warning", "results.ready"]
}

The list shows each event name once: hci.warning arrives once per batch you send, only for an indicator your context includes, and it is not an alert: DevLab does not show the level that triggers it (threshold), so do not build on it. Whether it is sent depends on the environment.

Engine has no webhooks: you use the event stream or you poll. The only webhook in the system is the processing service’s, to your backend, in deferred.

Save userProtocolId and protocolMechanicId in your backend when you enrol, not in the tab: E_RESULTS_TIMEOUT is not a loss, and with the pair you read the results later. Store your opaque externalId with them too, never the email: it is what deletes the person. Engine does not expire results today: they stay until admin.deleteUser(externalId) (DELETE /users/{externalId}) deletes the person and everything of theirs, which cannot be undone (Deletion and retention). What else to keep, and how to read the interpretation again for free: What to keep.

The catalogue (GET /catalog/protocols, GET /catalog/contexts), a person’s state (GET /users/{externalId}/status) and their enrolments (GET /users/{externalId}/user-protocols, or admin.listEnrolments) are plain reads from your backend. See the HTTP API guide and the API reference.

The interpretation is read the same way: admin.analyze(pair) returns the stored one (fromCache: true) when the analysis came out complete; with metadata.status degraded or failed, or none stored yet, every call regenerates it, which costs language-model tokens and time: generating an interpretation usually takes tens of seconds and can take about two minutes end to end (The interpretation): ask once, never in a loop. Which audience to send so it comes from the cache: What to keep. To force a new one, and when not to: Ask for a fresh interpretation. Since capture-server 0.16.0, AnalyzeResult.structured carries the interpretation’s structured data whole; a 0 to 100 index, when the domain has one, is read from it with readScoreIndex(result.structured) (A 0 to 100 index).

With the SDK in real time there is one interpretation per session since 0.38.0: the stored one. The text the person saw on the page is the one admin.analyze(pair) returns afterwards (fromCache: true), because stop() waits for Engine’s notice and, if it does not arrive, reads it once with POST /analyze instead of generating another. SessionReport.interpretationSource (in the page) says where it came from; 'analyze-generated' means /analyze had to generate one, and the session may have been interpreted twice. Up to 0.37 there were two interpretations of one session, both billed: see two interpretations. Over the HTTP API, every call to /analyze/stream still generates a new one that Engine does not store; with the SDK, only if you ask for interpretation: 'stream'.

How the analysis came out is metadata.status; the rest of metadata (model, token counts, ids, timings) is internal to Engine. This documentation does not promise those fields: do not build on them or show them to your users, because they can change or disappear without notice.

createWebhookHandler({ secret, nonces, onEvent }) verifies each delivery. What you can rely on:

  • The signed fields are in the body: ProcessorWebhookEvent.jobId, ProcessorWebhookEvent.captureId, ProcessorWebhookEvent.status (succeeded, failed or, since capture-server 0.11.0, the non-terminal interpreting), ProcessorWebhookEvent.interpretation (on a succeeded), ProcessorWebhookEvent.outcome, ProcessorWebhookEvent.errorCode, ProcessorWebhookEvent.retryable.
  • X-Neuro-Delivery and X-Neuro-Job travel outside the signature: a hint, never an authority.
  • The signature is valid ±300 s around your server’s clock and each nonce is kept 600 s, so keep the clock in sync.
  • Deliveries are at least once and in no guaranteed order: act only if the jobId in the body is the one you saved and the job you stored is still in flight: the status in your table, or the one processor.getJob returns, is one of queued, downloading, preparing, transcribing, replaying, waiting or interpreting (ProcessorJobStatus). The status of the event itself is succeeded or failed (terminal) or interpreting (an interim notice that closes nothing). Do nothing on a second event, and nothing on an interpreting that arrives after the terminal one.
  • Answer 2xx quickly and do the work afterwards.
  • HTTPS only.
  • Exempt this route from your framework’s CSRF protection (it is signed, not a browser form).

If a delivery never arrives, poll with processor.getJob(jobId). The handler takes a single secret, so it cannot accept two at once: rotating it means a brief cut, and if you cannot afford one, poll with processor.getJob while you change it.

JavaScript
import { createProcessorClient } from '@neurologyca/capture-server'
const processor = createProcessorClient({ url: process.env.PROCESSOR_URL, apiKey: process.env.PROCESSOR_API_KEY })
const job = await processor.getJob(jobId) // the same state the webhook carries, when you need it

Since capture-server 0.11.0 the job waits for the interpretation: succeeded arrives once it is ready or once it is known it will not come, and its interpretation says which. The job is a success whatever that value is: the indicators are in /results. What to do with each value: The interpretation.

To test your handler without the service, sign a synthetic event yourself and post it to your route. capture-server verifies signatures but does not make them, so this is the format it checks: the header X-Neuro-Signature: t=<epoch ms>,n=<uuid>,v1=<hex>, where v1 is the HMAC-SHA256, with your secret, of webhook.<t>.<n>.<raw body> (the exact bytes you post). Use a current t (±300 s) and a new n each time.