Certificate timeline & events
Every certificate in CertAutoPilot carries a timeline of every lifecycle event — request, approval, issuance, renewal, distribution, revocation, download. Events are event-sourced (not log-parsed) and stored in the cert_events collection with cursor-based pagination; the timeline surface in the UI is just a read over this collection.
Event types
| Type | When emitted | Payload highlights |
|---|---|---|
cert.requested | Issuance form submitted | actor, issuer, subject |
cert.approved | Approval request accepted (if policy gates issuance) | approver, approval_id |
cert.issued | CA returned the certificate | fingerprint, not_before, not_after, chain_depth |
cert.renewed | Renewal (or reissue) succeeded | trigger (scheduler/manual/reissue), new fingerprint |
cert.failed | Issuance or renewal failed | error |
cert.reissued | Reissue succeeded | new fingerprint |
cert.imported | An externally issued certificate was imported | fingerprint |
cert.revoked | CA confirmed revocation | reason_code, reason, actor, note |
cert.distributed | Distribution finished successfully | distribution_id, module, targets_succeeded |
cert.distribution_failed | Distribution ended in failed / partial | distribution_id, error_class, targets_failed |
cert.downloaded | Manual download through the UI or API | format, actor, ip |
That is the complete list — eleven types, and nothing else appears on a timeline.
Expiry and renewal-failure are notification events (cert.expiring_soon, cert.expired, cert.renewal_failed, cert.revocation_detected), delivered through notification channels and syslog. They are a different set from the timeline events above and never appear here — a renewal failure shows on the timeline only as the generic cert.failed, and an expiry produces no timeline entry at all. Point alerting at the notification system, not at this endpoint.
How events are emitted
A singleton CertEventEmitter injected into every service calls Emit() synchronously from the domain code. Emission is best-effort — a transient Mongo write failure is logged but does not block the action. For critical audit trails use the separate HMAC-chained audit logs which are transactional.
Timeline on the UI
- Certificate detail page → Timeline tab.
- Filter by event type (checkboxes).
- Cursor-based pagination (the server returns 50 events per page with a
next_cursorpointer). - Each entry expands to show the full payload + actor identity.
Query via API
GET /api/v1/projects/{projectId}/certificates/{id}/timeline
?cursor=<opaque>
&limit=50
&limit=100
&cursor=<opaque>
Returns the events plus a next_cursor when more pages are available. See API reference.
Retention
Events carry a 365-day TTL: MongoDB expires each one a year after its timestamp, automatically. If your compliance policy needs a longer horizon, export the timeline before the year is out — raising the retention means altering the TTL index on cert_events.
Routing to notifications
Every event can trigger a notification rule. See notifications → event types for the full mapping and templating.
Troubleshooting
Expected event missing from the timeline
Emission is best-effort; a transient Mongo issue can drop an event. Cross-check with Jobs (every workflow writes a job record) or the Audit log (transactional and chained).
Events arrived out of order
Events are timestamped at emit. Clock skew between API/worker/scheduler pods can produce sub-second out-of-order display. Order by seq (monotonic per-cert counter) rather than timestamp for strict ordering.