Skip to main content
Video tutorial · 2:31

Notifications

35 subscribable event types across Email, Slack, Microsoft Teams and generic webhooks. Per-event templates with Go variables, delivery via the job queue, and per-project routing.

Event catalog​

Every notifiable event has a stable name. Subscribe channels to event names with optional severity filters.

EventFires when
cert.issuedA certificate is issued for the first time.
cert.renewedA renewal completes successfully.
cert.renewal_failedA renewal attempt fails.
cert.issuance_failedA first issuance or a re-issue fails and is not retried (ACME, manual DNS, AD CS, CA connectors) — also a re-issue left unfinished that a background sweep restores. A CA-connector first issuance refused before any domain validation or order was started (for example DOMAIN_NOT_VALIDATED) is recorded in the certificate's Last error only.
cert.expiring_soonA certificate needs attention before it expires — see When an expiry alert is raised.
cert.expiredA certificate has expired (once per expiry, critical) — also one stuck in a failed renewal.
cert.revokedA certificate is revoked from CertAutoPilot.
cert.revocation_detectedThe CA revoked a certificate out-of-band (detected by the revocation sweep).
cert.revocation_failedA revocation attempt failed terminally at the CA — the certificate may still be trusted.
cert.chain_warningA stored version does not serve the chain chosen for the certificate (see Certificate chain).
cert.chain_changedThe CA delivered the new version with a chain that ends at a different root than the previous version's — the CA moved roots. The certificate's own chain choice is not counted.
chain_certificate.expiringA chain catalogue certificate that certificates use expires in 30, 14 or 7 days and has no successor.
chain_certificate.revokedThe CCADB starts listing a chain catalogue certificate that certificates use as revoked. Sent once, to every project whose certificates use it.
distribution.successA distribution completes successfully (one event per distribution, including fan-out).
distribution.failedA distribution fails or completes partially.
distribution.rollback_successA distribution rollback succeeds.
distribution.rollback_failedA distribution rollback fails (or cannot be enqueued).
job.failedA background job fails terminally and its job type has no failure event of its own (coalesced to one alert per job type per hour).
domain.expiring_soonA tracked domain registration is close to expiry.
domain.expiredA tracked domain registration has expired.
domain.dangling_dnsDNS for a tracked domain points at a resource that no longer exists (takeover risk).
domain.dnssec_missingA tracked domain has no DNSSEC at the registrar.
domain.no_dmarcA tracked domain has no DMARC policy.
approval.requestedAn operation requiring approval is requested.
approval.approvedAn approval request is approved.
approval.rejectedAn approval request is rejected.
approval.executedAn approved operation is executed.
approval.expiredAn approval request expires unanswered.
discovery.new_certA discovery scan finds a certificate it has not seen before.
discovery.cert_changedA discovery scan sees a different certificate on a known endpoint, or the TLS settings of an endpoint got worse while its certificate stayed the same (TLS version lowered, weaker cipher, chain no longer trusted).
discovery.kex_downgradedA server that negotiated a quantum-safe key exchange negotiates a classical or RSA one (one summary per source when more than five in a scan).
discovery.endpoint_goneA previously-scanned endpoint stops answering.
discovery.finding_openedA discovery finding opens, is detected again after it was resolved, or becomes more severe (one summary per source when more than five change at once).
discovery.cert_expiringA discovered certificate CertAutoPilot does not manage — or an earlier version of one it manages that a server still serves (managed_certificate_id set) — reaches an expiry lead time (once per lead time, daily in its last three days; one summary per source when more than five are due at once).
discovery.cert_expiredA discovered certificate CertAutoPilot does not manage has expired (once; one summary per source when more than five expired at once).
Discovery events

Discovery also surfaces its results as findings. The scan events (new_cert, cert_changed, endpoint_gone) fire during scans; finding_opened, cert_expiring and cert_expired fire when findings are recomputed — after every scan and once an hour. See Findings → Notifications for the rules.

Channels​

Configure under Settings → Notifications → Channels.

  • Email — SMTP host, port, STARTTLS / TLS, auth. Per-recipient lists.
  • Slack — incoming webhook URL. Bot OAuth tokens are not supported.
  • Microsoft Teams — Workflow URL (Power Automate) or legacy connector.
  • Webhook — any endpoint that accepts a JSON POST. Optional HMAC signing (X-Signature-256), bearer auth, and custom headers — a custom header whose name carries a credential (Authorization, X-Api-Key, anything with auth/token/secret/key/cookie/password/credential/signature in it) is shown masked in the channel summary and in the audit record of an edit; sending the mask back on edit keeps the stored value, and a mask under a header name that has no stored value (a renamed header) is refused so the literal mask is never saved. Distinct from the Webhook distribution target, which delivers certificates — this channel delivers event notifications.

Webhook delivery format​

Every delivery is a POST with Content-Type: application/json:

{
"event_type": "cert.renewal_failed",
"severity": "warning",
"subject": "Certificate renewal failed: example.com",
"message": "Renewal for example.com failed: ...",
"project_id": "…",
"certificate_id": "…",
"timestamp": "2026-08-17T10:00:00Z",
"data": { "primary_domain": "example.com", "error": "…" }
}

Any 2xx response counts as delivered; a 4xx (other than 429) is treated as permanent and not retried; 429/5xx/transport errors get up to 3 delivery attempts in total. Redirects are never followed — auth headers must not travel to a location a receiver chooses.

Headers on every request: User-Agent: CertAutoPilot/1.0, X-Timestamp (RFC3339), your custom headers (Host, proxy and hop-by-hop headers are ignored), and — when a signing secret is configured — X-Signature-256: sha256=<hex> computed as HMAC-SHA256 of the raw request body. Verify it like a GitHub webhook:

const crypto = require('node:crypto');
const expect = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(req.headers['x-signature-256']));

Once set, the signing secret and bearer token cannot be cleared in place — a blank value on edit means "keep the stored one" (the same rule every masked field follows). To turn signing or bearer auth off, recreate the channel without them.

A stored secret is never kept for a new destination: an edit that changes a webhook's URL while leaving its secret, bearer token or a masked header value blank is refused (CHANNEL_CREDENTIAL_REQUIRED) — enter them again. The same holds for an SMTP channel's password when the server, port or TLS mode changes, or certificate verification is turned off.

Plain HTTP is allowed — deliberately

Unlike Slack/Teams, a webhook channel URL may use http:// so internal receivers work without TLS. On plain HTTP the signing secret's signature, bearer token and payload travel unencrypted on your network — prefer HTTPS whenever the receiver supports it. Link-local and cloud-metadata addresses are always refused, and URLs may not embed credentials.

Toggling a channel off stops all delivery through it — rules pointing at a disabled channel are skipped (recorded in History as channel is disabled), even if the rules themselves stay enabled.

Templates​

Each event has a built-in default template; org-level custom templates can override it per channel type. Variables are exposed via Go templating as flat, pre-formatted strings — for example:

Subject: Certificate Expiring Soon: {{.primary_domain}}

<p>Certificate <b>{{.primary_domain}}</b> expires in {{.days_remaining}} day(s).</p>
<p>Expires: {{.expires_at}}</p>
<p>{{.reason_text}}</p>
<p>Certificate: {{.certificate_id}}</p>

{{.event_type}}, {{.certificate_id}}, and {{.job_id}} are available on every event; the rest ({{.primary_domain}}, {{.error}}, {{.expires_at}}, {{.domain_name}}, …) vary per event. No template functions are registered, and missing variables render as empty strings. Custom templates are per channel type (email HTML vs Slack/Teams plain text). See Notification templates for the full per-event variable reference.

When an expiry alert is raised​

cert.expiring_soon follows each certificate's own renewal plan instead of one fixed window, so short lifetimes and short renewal thresholds do not turn into daily noise:

CertificateAlerted whenHow often
Renewed automatically (auto-renew on)Its planned renewal (next_renewal_at) is overdue by more than the Overdue Renewal Grace (default 24 h), or automatic renewal has stopped. A renewal running on schedule never alerts, whatever its threshold.Once a day while overdue (reason: renewal_overdue)
Not renewed automatically (imported, auto-renew off, manual DNS)It reaches one of the Expiry Alerts lead times (default 30, 14, 7 and 1 days before expiry). A lead time longer than a third of the certificate's lifetime is shortened to that third, so a short-lived certificate is not alerted for most of its life.Once per lead time (reason: manual_renewal_due)
Any certificateIt is in its last 3 days.Once a day, severity critical (reason: final_days)

Both settings are on Settings → General and apply to the whole organization. A renewal gives the certificate a new expiry, so its alerts start again from the first lead time. cert.expired fires once when a certificate expires — including one left in renewal failed, which never changes status by itself — and only for expiries within the last 30 days.

The payload carries days_remaining (rounded up), reason, reason_text (the same as a sentence), next_renewal_at and renewal_threshold_days — see Notification templates.

The dashboard's expiring soon figure and the certautopilot_certificates_expiring_soon metric still count certificates expiring within 30 days; they are indicators, not alerts.

Routing​

A rule binds one or more event types to a channel:

  • Severity at least (severity_min) — e.g. warning filters out info noise.
  • Project — rules are project-scoped; a rule only matches events from its project.
  • Recipients — set on the rule, not the channel. For SMTP rules at least one address is required (the channel config carries none), each must be a valid address, and the list is capped at 50.
  • Message Template (optional) — a specific template to render this rule's events. Leave empty to use the channel's default / built-in per-event message. Its channel type must match the rule's channel. Assigning different templates to different rules is how you get different messages for different events.

Multiple rules can match the same event; each fires independently (so avoid unintended overlap). A rule listing several events renders one template for all of them — split into separate rules, or guard event-specific variables with {{if}}, when the messages should differ.

Delivery & retries​

Each matched rule enqueues a notification.send job. Delivery is retried by the job queue (up to 3 attempts with backoff); after the final failure the job is marked failed. Sent and failed deliveries surface under Settings → Notifications → History with their status and last error — there is no separate dead-letter buffer beyond the job queue itself. A delivery to a channel that has since been disabled is recorded with status skipped. History rows are kept for 90 days.

Why a persistent condition only alerts once​

Deliveries are de-duplicated. Before sending, the job reserves a history row keyed on (rule, certificate, event type, time bucket) behind a unique index, so a second event falling in the same bucket is dropped rather than delivered. The bucket depends on the event:

EventBucket
cert.expiring_soonone per lead time (tier:<days>:<expiry>); once a day while a renewal is overdue or in the last 3 days (overdue: / final:<expiry>:<date>)
cert.expiredonce per expiry (expired:<expiry>)
domain.expiring_soon, domain.dnssec_missing, domain.no_dmarcone per week
domain.dangling_dnsone per day
domain.expiredonce per domain (on the transition to expired)
job.failedone per job type per hour
approval eventsone per request

The expiration check also records the last alert on the certificate before raising it, so each expiry alert is raised once even when several workers run the check. The bucket is also what {{.job_id}} shows for these events. If you expect an alert and do not get one, check History for an existing row in the current bucket before suspecting the channel.

Testing a channel​

Each channel has a Send test button — fires a fixture event and reports the channel's response. Always click it after creating or editing a channel.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Email Notifications, Scheduled Reports and Syslog to Your SIEMYouTube ↗