Skip to content
HostTracker Docs

TLS handshake policy

View as Markdown

By default an HTTPS check only needs the TLS handshake to complete: an expired, self-signed or otherwise invalid certificate does not by itself make the site “down”, as long as the connection negotiates and the server answers. That keeps “certificate problem” and “site unreachable” apart. When you want certificate and protocol quality to count as a failure, switch on the TLS Handshake policy.

Settings reference

Section titled “Settings reference”
Setting (app label) API field (settings.*) Type Default Plan limits What it does for you
Require valid SSL certificate chain requireValidChain Boolean Off SSL validation policies Fails unless the server presents a complete, trusted chain: an expired, self-signed, name-mismatched or mis-chained certificate fails.
Require strong TLS protocol (1.2 or higher) requireStrongTls Boolean Off SSL validation policies Fails when the connection negotiates TLS 1.0/1.1 or SSL.
Block weak ciphers (128-bit or lower) blockWeakCiphers Boolean Off SSL validation policies Fails when the negotiated cipher suite uses 128-bit or weaker encryption.
Check SSL certificate revocation checkRevocation Boolean Off SSL validation policies and revocation checking Verifies online (CRL/OCSP) during the handshake that the certificate has not been revoked; a revoked certificate fails.

The switches exist on Website/HTTPS, API and Port monitors (for Port, only while TLS is switched on for the connection).

Set it up in the app

Section titled “Set it up in the app”
  1. On Sites, open the monitor and expand Response Validation (for a Port monitor, its connection settings).
  2. Under TLS Handshake, switch on the policies you want.
  3. Save.

A switch your plan does not include is greyed out with “SSL validation policies are not available in your current plan.” (or “Revocation check is not supported in your package.” for revocation) and an Upgrade link.

Do it with the API or MCP

Section titled “Do it with the API or MCP”
Terminal window
# Require a valid chain and TLS 1.2+ (scope monitor:write)
curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "settings": { "requireValidChain": true, "requireStrongTls": true } }'

MCP: update_monitor with settingsJson {"requireValidChain":true,"requireStrongTls":true}; many monitors with bulk_update_monitors (patchJson {"settings":{"requireValidChain":true}}).

What happens next

Section titled “What happens next”

From the next check, a handshake that breaks a switched-on policy fails the check with a TLS error. Like any failure, it is re-checked from other locations before the monitor turns Down and alerts go out.

Limits and gotchas

Section titled “Limits and gotchas”
  • Turning on a switch your plan does not include is refused with 403 package_limit (“SSL validation policies are not available on your package” / “Certificate revocation checking is not available on your package”). Revocation needs both entitlements.
  • A switch already on stays on if you later move to a plan without it; it just cannot be switched on again there. Turning a switch off is never refused.
  • These switches judge the certificate at every check. To be warned ahead of expiry instead, use an SSL/TLS certificate expiry monitor or attach one to the website monitor - see Attached sub-checks.
  • With Require valid SSL certificate chain on, an expired certificate turns the monitor Down. If you only want an expiry reminder, leave it off. See Certificate expiry counted as downtime.
  • The old single field tlsChainFlags no longer exists; sending it is refused (422).
Section titled “Related”