Service monitors (ports, APIs & heartbeats)

Not everything worth watching is a web page. A service monitor keeps an eye on the moving parts behind your site: an API your app depends on, the mail server that sends your receipts, a login endpoint, any service listening on a network port, or a scheduled job that must run on time. If it stops answering, answers wrongly, or stops checking in, TLDTrack tells you. If it answers slowly, it is marked as degraded.

The three kinds of check

When you create a service monitor you first choose what kind it is. Everything else on the form changes to match.

• HTTP check. Best for anything that speaks the web: a REST or JSON API, a health-check endpoint, a webhook receiver, an admin login page, or a subdomain. You give it a URL and TLDTrack requests it on a schedule.
• Port check. Best for services that are not web pages: a mail server (IMAP, SMTP or POP3), a database port, or any custom TCP service. You give it a host and a port number and TLDTrack opens a connection to see if the service is alive.
• Heartbeat check. Best for things TLDTrack cannot reach from outside: a nightly backup, a queue worker, a report generator, or any cron job. The direction is reversed: your job pings a secret TLDTrack URL each time it runs, and you are alerted when the pings stop.

HTTP checks: what you can set

An HTTP check does more than "did the page load". You can tell it exactly what a healthy response looks like:

• URL. The full address to request, for example https://api.example.com/health.
• Method. Usually GET, which is the default. You can pick another method if your endpoint expects it.
• Expected status. By default any success code (a 2xx) is treated as healthy. You can require a specific code instead, for example 200. Redirects are followed, so the code checked is the one from the final page.
• Latency threshold (optional). A response time in milliseconds. If the service answers correctly but slower than this, it is marked degraded rather than healthy, so you can see it slowing down before it fails outright. Degraded does not send an alert.
• Content assertion (optional). Go beyond the status code and check the body of the response:
  • Body contains a piece of text, for example the word healthy on a status page.
  • JSON path equals a value, for example the field at status being ok in a JSON health response.
  • Either assertion can be negated, so you can alert when a phrase such as maintenance or error appears instead of when it is missing.

Port checks: what you can set

A port check confirms that a non-web service is accepting connections, and optionally that it greets you correctly:

• Host and port. The server and the port number to connect to, for example mail.example.com on port 993.
• Protocol. Choose tcp, imap, smtp or pop3. This labels the monitor; the check itself is the same connection test for each. For STARTTLS, the command is picked by port number: SMTP on 25 or 587, POP3 on 110, and IMAP style on any other port.
• TLS mode. Choose none for an unencrypted port, implicit for a port that is encrypted from the start (such as IMAP on 993 or SMTPS on 465), or starttls for a port that upgrades to encryption after connecting (such as SMTP on 587). A failed TLS handshake counts as down.
• Expected banner (optional). Many services send a greeting line when you connect. You can require that greeting to contain a certain phrase, so you catch a wrong or misconfigured service answering on the right port.

Heartbeat checks: watching a cron job

A heartbeat monitor works the other way round from the first two kinds. Instead of TLDTrack calling your service, your job calls TLDTrack. When you save the monitor you get a secret ping URL that looks like this:

https://www.tldtrack.com/ping/YOUR_TOKEN

Your job requests that URL every time it runs. A plain GET is enough, and POST and HEAD requests work too, so anything from curl to a webhook sender can check in; the endpoint answers OK. The simplest way to wire it up is one extra line in your crontab:

*/5 * * * * curl -fsS --retry 3 https://www.tldtrack.com/ping/YOUR_TOKEN > /dev/null

You set two numbers on the monitor:

• Expected check-in. How often the job should ping: every 5, 10, 15 or 30 minutes, hourly, every 6 or 12 hours, or daily. Match it to the job's own schedule.
• Grace time. Extra minutes allowed after the period before TLDTrack alerts, 5 by default. This absorbs normal jitter: a backup that sometimes takes a little longer, or a cron host under load. A daily job with a 30 minute grace alerts only once the ping is more than 30 minutes late.

When a ping has not arrived within the period plus grace time, the monitor goes down: an incident opens and you are alerted within minutes. The moment the next ping arrives, the monitor recovers instantly and a recovered alert is sent. Like the other kinds, a heartbeat monitor keeps its own 90-day uptime bar, so a job that misses now and then shows up clearly. Keep the URL secret; anyone who has it can mark the job as healthy.

If you pause a heartbeat monitor, its alerts stop but incoming pings are still recorded, so a job that kept running while paused does not show as overdue the moment you switch it back on.

What you need before you start

A service monitor is quick to set up, but a few things need to be true for it to work:

• A website to attach it to. Service monitors live under one of your sites. Add the site first if you have not already (see Add your first website).
• The service must be reachable from the public internet. TLDTrack checks from our servers, not from inside your office or VPN. Something that only answers on localhost, a private network, or behind an IP allowlist cannot be reached. If you use a firewall or allowlist, permit our checks or expose a safe public health endpoint. Heartbeat checks are the exception: nothing on your side needs to be reachable, because your job makes an outbound request to us instead.
• The details of a healthy response. For an assertion, know the exact text, or the JSON path and value. For a mail port, know the port number and whether it uses implicit TLS or STARTTLS.
• Room within your limit. Each organisation can create up to its service-monitor limit, which is 5 by default and separate from your website count. Service monitors do not consume website slots.

What the statuses mean

Every check settles on one of these:

• OK. The service answered correctly and within your latency threshold.
• Degraded. The service answered correctly but slower than the latency threshold you set. A warning sign, not an outage.
• Down. The service failed: no connection, a wrong or failed status, a failed TLS handshake, or a content or banner assertion that did not match.
• Error. The check itself was inconclusive, for example a problem on our side. This is treated as "we could not tell" and is deliberately not counted as a real outage, so a blip in our own probe never raises a false alarm.

How alerting works

Service monitors also wait for confirmation before alerting, though more simply than uptime monitoring: there is no instant retry and no second checking region. A single failed check does not alert. The service has to fail two scheduled checks in a row before it is treated as genuinely down. At that point:

• An incident opens with a timestamp, and a critical alert is emailed to the notification contacts who receive uptime alerts. It also goes to any connected Slack, Teams or webhook channel. Service monitor alerts are not sent by SMS or push.
• While the service stays down, you are not spammed with repeat alerts for the same incident.
• When it starts responding again, the incident closes with its total duration recorded, and a recovered alert is sent so you know it is back.

Alongside incidents, each monitor keeps a rolling 90-day uptime bar so you can see reliability at a glance and spot a service that fails intermittently rather than staying cleanly up or down.

How to set one up, step by step

1. 1
   Open the website this service belongs to from your Domains list, and go to its APIs / External Monitoring tab.
2. 2
   Choose Add service and give it a clear label, for example "Booking API" or "IMAP mail", so an alert tells you instantly what broke.
3. 3
   Pick the kind: HTTP for a URL or API, Port for a mail server or raw TCP service, or Heartbeat for a cron job or scheduled task that will ping TLDTrack itself.
4. 4
   For an HTTP check: enter the URL, then tighten it up if you want by requiring a specific status code, setting a latency threshold to catch slowness, and adding a body-contains or JSON-path assertion so you are checking the real answer, not just that something replied.
5. 5
   For a port check: enter the host and port, choose the protocol (tcp, imap, smtp or pop3), set the TLS mode (none, implicit or starttls), and optionally require a phrase in the greeting banner.
6. 6
   For a heartbeat check: choose the expected check-in period and a grace time, save, then copy the ping URL into your cron job or script.
7. 7
   Choose how often it runs: every 5 minutes, every 15 minutes, hourly, or daily. Five minutes is the default and is right for anything customer-facing.
8. 8
   Save. The first check runs within a few minutes, and from then on the service is watched on your chosen schedule, with history and incidents building up automatically.

Worked examples

A few common set-ups, so you can see how the pieces fit together:

• A REST API health endpoint. HTTP check on https://api.example.com/health, expected status 200, JSON-path assertion that status equals ok, every 5 minutes.
• Incoming mail (IMAP). Port check on mail.example.com port 993, protocol imap, TLS mode implicit, every 15 minutes.
• Outgoing mail (SMTP submission). Port check on mail.example.com port 587, protocol smtp, TLS mode starttls, with an expected banner phrase, hourly.
• A slow-but-critical report endpoint. HTTP check with a latency threshold set, so it shows as degraded before it times out completely.
• A nightly backup. Heartbeat check with a daily period and a 60 minute grace, and a curl ping as the last line of the backup script. If the backup fails or never runs, the ping never arrives and you are alerted.

Where to set this up

Good to know

• Service monitors do not use a website slot. They count only towards your separate service-monitor limit (5 by default).
• You can switch a monitor off temporarily without deleting it, which keeps its history.
• Use a service monitor, not uptime monitoring, whenever the thing you care about is an API, a subdomain endpoint, or a non-web service rather than the main website page.