Reference
Ledger events
The full list of event types that can appear in your firm's ledger chain, with their corresponding webhook event names.
Every entry in the ledger has an eventType. The set is closed and versioned — new event types are additive only, never renamed. The values below match the LedgerEventType enum in @bedrock/types.
| Event type | Description | Webhook |
|---|---|---|
DOCUMENT_SUBMITTED | A new piece of advice has been submitted for review. | job.submitted |
REVIEW_STARTED | A reviewer has opened the document and begun the review session. | review.started |
REVIEW_COMPLETED | A reviewer has submitted their decision (approve / modify / reject). | review.completed |
DOCUMENT_APPROVED | The reviewer approved the document as drafted. | document.approved |
DOCUMENT_MODIFIED | The reviewer approved with modifications. The modifications are recorded verbatim. | document.modified |
DOCUMENT_REJECTED | The reviewer rejected the document. A rejection reason is recorded. | document.rejected |
CERTIFICATE_ISSUED | Deprecated. The worker no longer emits this event — a certificate is just a presentation envelope around an already-signed ledger record. To know when a certificate exists, subscribe to the underlying event type (e.g. DOCUMENT_APPROVED) and look up the certificate by `ledgerRecordId`. | — |
SLA_BREACHED | A review job has crossed its SLA deadline without a decision. | sla.breached |
IMPACT_ASSESSMENT_APPROVED | A Consumer Duty impact assessment for an AI use case has been approved and signed off by a senior (PRIN 2A · SYSC 7.1). | impact-assessment.approved |
INCIDENT_LOGGED | An operational or compliance incident has been recorded against the firm (FG21/1 · SYSC 15A). | incident.logged |
INCIDENT_RESOLVED | A previously-logged incident has been resolved or closed. | incident.resolved |
FIRM_SETTINGS_UPDATED | A compliance-relevant firm setting (e.g. enforceImpactAssessments) was toggled. The snapshot carries the field-level diff and the authenticated actor. | firm-settings.updated |
Review lifecycle
A successful job produces this sequence of events:
DOCUMENT_SUBMITTEDREVIEW_STARTEDREVIEW_COMPLETED- One of
DOCUMENT_APPROVED/DOCUMENT_MODIFIED/DOCUMENT_REJECTED
The outcome event is the certificate's anchor — there is no separate CERTIFICATE_ISSUED event. Certificate generation runs asynchronously after the outcome record is written; once cert-gen finishes, the certificate is available via GET /v1/ledger/records/{id}/certificate using the outcome record's id. Subscribers wanting “tell me when a certificate exists” should subscribe to the outcome event types and resolve the certificate by ledgerRecordId.
Impact assessment lifecycle
Consumer Duty impact assessments are filed at POST /v1/firm/me/impact-assessments and progress DRAFT → PENDING_SIGNOFF → APPROVED. Only the approval step produces a ledger event:
IMPACT_ASSESSMENT_APPROVED— when a senior (LEAD_REVIEWER or FIRM_ADMIN) transitions the assessment toAPPROVED. The snapshot (assessment id, use case, model provider/version, template version, outcomes, signer) is hashed and anchored to the ledger.
With the firm's enforceImpactAssessments gate on (the default), jobs declaring a modelProvider/modelVersion must have a matching approved assessment or submission returns 409 IMPACT_ASSESSMENT_REQUIRED. See Impact assessments for the full lifecycle and enforcement semantics.
Firm settings audit trail
Compliance-relevant firm settings (currently enforceImpactAssessments, more to come) emit a FIRM_SETTINGS_UPDATED ledger event whenever they change value. The snapshot anchored to the ledger carries:
actorType—USERorAPI_KEYactorId/actorName— who made the changechanges— array of{ field, from, to }diffs
No-op PATCHes (where the incoming value already matches the stored value) are ignored — they don't write to the database and don't emit a ledger record. Only compliance-relevant settings are on the allowlist; operational fields like display name do not produce a ledger event.
Incident lifecycle
Incidents are written through POST /v1/firm/me/incidents and progress through their own two-event lifecycle:
INCIDENT_LOGGED— on creationINCIDENT_RESOLVED— when the status transitions toRESOLVEDorCLOSED
Both events anchor the incident snapshot in the immutable ledger so the firm's incident history can't be rewritten after the fact. See Incident response for the full shape of the metadata carried in each event.