SSL certificate monitor

The SSL monitor opens a TLS connection to a hostname, inspects the served certificate, and warns you before it expires. Every check also records a full snapshot of the certificate and the TLS connection — issuer, fingerprints, key type, SANs, chain validity, cipher and more — so you can alert on certificate changes, not just expiry.

Configuration

Field	Type	Default	Notes
Hostname	string	—	Domain to connect to. If you paste a full URL, the scheme, port and path are stripped automatically.
Port	integer	`443`	1–65535.
Alert before expiry	days	`30`	Minimum 1. The monitor turns Degraded when remaining validity drops to this number of days or below.
Timeout	ms	`10000`	1000–30000. Maximum time to complete the TLS handshake per IP family.
IP versions	array	`["ipv4", "ipv6"]`	Which families to test. At least one. Cloud regions run IPv4 only — see IPv6 monitoring.

How it works

For each selected IP family the monitor resolves the hostname, opens a TLS connection to the resolved address (using the hostname for SNI), and reads the certificate the server presents. Each family produces its own sub-result; the monitor’s overall status is the worst across families, and the reported response time is the average of the families that connected.

If the runner has no outbound connectivity for a selected family, that family is recorded as skipped and does not affect the overall status.

Status mapping

Outcome	Status
Certificate valid, more than `alert_before_expiry_days` days remaining	`up`
Certificate valid but expiring within `alert_before_expiry_days` days	`degraded`
Certificate expired	`down`
Connection refused, TLS handshake failure, no certificate served, timeout, no DNS record for a selected family	`down`

Status is driven by expiry and connectivity only. Chain validity, self-signed certificates and hostname/SAN details are reported in the result data (below) so you can alert on them with alert rules, but they do not by themselves change the check status.

Result data

Every check stores the full certificate and connection details:

Field	What it is
`subject` / `subject_org`	Certificate common name and subject organisation.
`issuer` / `issuer_org`	Issuing CA common name and organisation.
`valid_from` / `valid_to`	Certificate validity window.
`days_remaining`	Whole days until `valid_to`. Negative once expired.
`serial_number`	Certificate serial.
`fingerprint` / `fingerprint256`	SHA-1 and SHA-256 fingerprints — useful for detecting unexpected certificate swaps.
`key_algorithm` / `key_bits` / `key_curve`	Public key type (`RSA`, `ECDSA`), key size, and curve name for ECDSA keys.
`alt_names` / `ip_sans`	DNS and IP Subject Alternative Names.
`tls_version`	Negotiated protocol (e.g. `TLSv1.3`).
`cipher` / `cipher_standard_name`	Negotiated cipher suite (OpenSSL and IANA names).
`chain_valid` / `chain_error`	Whether the chain verifies against trusted roots, and the validation error if not.
`is_self_signed`	Whether the served certificate is self-signed.
`chain_depth`	Number of intermediates between the leaf and the root the server presented.
`pfs_enabled` / `key_exchange`	Whether the connection used an ephemeral key exchange (Perfect Forward Secrecy), and which one.
`ocsp_url` / `ca_issuer_url`	The certificate’s OCSP responder and CA issuer URLs, as published in the certificate. Reported for reference — the responder is not queried.
`protocols`	Per-IP-family sub-results: status, response time and error message for each family tested.
`ip_versions_tested` / `ip_versions_skipped`	Which families actually ran and which were skipped.

When both IP families run, the certificate fields above come from the first family that returned a certificate.

Interval floors

SSL state changes on the order of months. Floors apply on top of the plan-wide minimum interval — see Limits & quotas.

Tips

The degraded window is your renewal runway: set alert_before_expiry_days comfortably above your renewal automation’s cadence (30 days suits most ACME setups).
Pair with a domain expiration monitor on the apex — the two long-tail expiries (certificate and registration) then show up on the same dashboard.
To catch unexpected certificate replacement (a possible sign of interception or misissued certs), use an alert rule on the certificate-changed condition — the fingerprints in the result data drive it.