Monitoring

The engine reports its own health over the API, and announces every control event to its event feed and to your webhooks. A monitoring system reads all of it under the monitor role, without any of the book’s detail.

What to read

Read	Who	What it says
`GET /v1/health`	Anyone, with no token: a load balancer can ask	Whether the ledger and PQS answer, the ledger’s latency, and how far PQS trails the ledger
`GET /v1/system`	`monitor`, `operator`, `risk`, `auditor`	The sign-in mode, the venue’s party, the registrar and DA’s operator, the ledger end, the asset records’ version, open settlements, reconciliation’s last run and cadence, PQS’s offsets, the time of its oldest transaction and how far it trails the ledger, retention’s cutoffs, each webhook’s deliveries, and which of NodeAsset’s packages your Canton node has
`GET /v1/reconciliation-verdict`	`monitor`, your staff, an integrating application	The latest run’s verdict and its count of blocking findings, and each asset held, with no finding’s detail
`GET /v1/events?kind=control`	`monitor`, your staff, an integrating application	Control events, in the order they were recorded
Webhooks	Your receivers	Control events as they happen, signed

Each section of the system view is read on its own: a view whose database does not answer still says who the engine is and where the ledger stands.

Health

{
  "offset": 18422,
  "now": "2026-10-03T08:00:00.120Z",
  "value": {
    "connected": true,
    "lastSyncedAt": "2026-10-03T07:59:58.400Z",
    "syncAgeMs": 1720,
    "latencyMs": 12,
    "projectionLag": 0,
    "message": null
  }
}

Field	Meaning
`connected`	`false` when the ledger or PQS does not answer; `message` then names which. The cause goes to the engine’s log, not to the caller
`latencyMs`	How long the read of the ledger’s end took
`projectionLag`	The ledger’s end minus PQS’s latest offset, at this instant
`lastSyncedAt`, `syncAgeMs`	When PQS’s latest transaction took effect, and how long ago; null when no time is known

PQS follows one party, so it moves only when that party’s ledger moves: a lag alone cannot tell a stuck projection from a quiet one. Compare the answer’s offset across reads: one that moves is not stuck.

What to alert on

Signal	Where it shows
The ledger or PQS does not answer	`connected: false` on health
The projection has stopped while the ledger moves	`offset` unchanged across reads, `projectionLag` growing
Reconciliation found a blocking finding	`reconciliation.finding`, `reconciliation.hold`; the verdict’s blocking count
A reserve’s cover fell below its minimum	`reserve.cover-low`, with the hold it placed
An outside statement is late	`statement.overdue`
A scheduled distribution has not run, or a standing approval’s run was refused	`distribution.due`
A holder was restricted, or an asset paused	`holder.restricted`, `instrument.paused`
Writes fail	`operation.failed` in the feed

Control events

Type	Announced when
`reconciliation.run`, `reconciliation.finding`	A reconciliation run finished; it found something
`reconciliation.hold`, `reserve.cover-low`	A blocking finding held an asset; a reserve’s cover fell short and its backed instrument was held
`hold.released`	A hold was released under two approvers
`statement.received`, `statement.overdue`	An outside statement was stored; a source fell overdue
`distribution.payable`, `distribution.held`, `distribution.paid`	A distribution became payable, was held, or had every line booked as paid
`distribution.rate-changed`, `distribution.due`	A period’s withholding rate changed and it ran under the alert setting; a record date passed with nothing distributed
`standing-approval.granted`, `standing-approval.revoked`	A standing approval was granted under its approvers, or revoked
`holder.restricted`, `holder.unrestricted`	A holder was frozen or limited to leaving; a restriction was lifted
`holder.forced-transfer`, `holder.recovered`, `instrument.paused`	A consented move ran; an asset was paused
`retention.pruned`	A retention pass deleted history, with a count per kind and the cutoffs it pruned by

The feed also carries each finished operation (operation.succeeded, operation.failed) and each four-eyes step (approval.requested, approval.signed, approval.approved, approval.rejected), and the ledger’s own facts as journal events. Webhooks carry the control events above.

Webhooks

Each webhook receives the types it takes, as a JSON post: type, at, the asset and the resource where there is one, and the event’s payload.

Header	Value
`X-NodeAsset-Event`	The event’s type
`X-NodeAsset-Delivery`	The delivery’s id: deduplicate on it
`X-NodeAsset-Timestamp`	Seconds since the epoch, at sending
`X-NodeAsset-Signature`	`sha256=` and the hex HMAC-SHA256, under the webhook’s secret, of the timestamp, a `.`, and the body

Verify every delivery in constant time, and refuse a timestamp far from your own clock: the timestamp is signed, so a captured post cannot be sent again later under a new one.
Delivery is at least once. A 2xx answer counts as delivered; anything else is retried with a doubling wait, and given up after the configured number of attempts.
Deliveries wait in an outbox in the engine’s database, so a restart loses none that were queued.

See Events and webhooks for receiving code.

The monitor role

monitor is the identity of dashboards and on-call. It reads health, the system view (with the projection’s reach and each webhook’s deliveries), the verdict and the feed’s control events, and nothing of the book:

A ledger fact names a holder’s party and units, so the monitor’s feed holds no journal events, only control events.
Each control event it reads is redacted. It keeps what happened, when, to which asset, and the ids, codes and counts its payload carries. It loses every free text and every person: a hold’s detail, a pause’s rationale, an approval’s reason, the maker, the approver.
The fields the monitor reads are allow-lists, so a new field reaches it as nothing until it is allowed.

A caller that holds another role too, such as an auditor, reads the whole feed. Related: Runbooks · Configuration reference · Segregation of duties

Architecture

Who runs what

Deploy

Operate

What to read

Health

What to alert on

Control events

Webhooks

The monitor role

​What to read

​Health

​What to alert on

​Control events

​Webhooks

​The monitor role

What to read

Health

What to alert on

Control events

Webhooks

The monitor role