Certificate renewal failure alerts
Overview
A failed CLM renew job raises cert_renewal_failed on the same channels as expiry and endpoint-health alerts: the alert queue, your delivery window, and the contact groups on the certificate's token.
Paths that can reach a terminal renew failure: the agent reports failed / blocked / policy rejected; the lease reaper marks orphaned_unknown_effect; forced agent retirement fences a held renew job; an external executor reports failed or rejected.
The transaction that records the failure also records the intent to alert. Contact resolution and queue insert run later. A skip (no token, no channel) is stored with its reason.
When it fires
| Fires | Does not fire |
|---|---|
renew reaches failed, blocked, or agent-side rejected | issue, deploy, reload, revoke, no-op |
renew reaches orphaned_unknown_effect (silent agent or forced retirement after running) | Approver reject or operator cancel |
Forced-retirement cancel of a held renew job | Dry run (dry_run_complete) |
Non-terminal statuses (pending, approved, claimed, running) | |
| No linked cert-category token, no workspace admin, or no email/webhook channel | |
Certificate retired as revoked or decommissioned |
The job timeline and audit log remain the source of truth. WhatsApp is not a channel for this alert type.
Issue vs renew
A failed renew means a live certificate with a real expiry was not replaced. A failed issue means a certificate you asked for was never created: nothing is serving, nothing is expiring. Watch provisioning inventory for issuance problems and this alert for renewal problems.
Idempotency
One alert per job, keyed cert_renewal_failed:<jobId>. A new job that also fails is a new alert.
Routing
Resolved from the failed job's managed certificate, in order: the linked token's assigned contact groups; else the workspace default; a deleted group falls back to the default. Email and webhooks follow those groups. Assign one or more groups with at least one email contact or webhook, or set a workspace default. Delivery still respects the delivery window.
The payload carries certificate identity and the frozen error code. Open the job timeline for evidence. The queue stores ids and the error code.
If a failure produced no alert
- Was the operation
renew? A failedissuedoes not alert. - Did a human reject or cancel the job? Forced-retirement cancel does alert.
- Is the certificate linked to a token?
- Do the assigned contact groups have email or a live webhook?
- Was the certificate retired?
Plan availability
Pro and Team. Reuses your existing alert channels.