Documentation

Getting started

After creating an account, head to Monitors and add the first thing you want watched. A monitor can be an HTTP endpoint you want checked from the outside, or a heartbeat that your own code or cron job pings on a schedule.

1. Create a monitor and choose a check type: HTTP or Heartbeat.

2. Set how often it should be checked, and how many consecutive failures confirm an incident.

3. Attach a notification channel so you hear about it the moment something changes.

HTTP monitors

An HTTP monitor requests a URL on an interval and checks the response. You can configure:

• Method — the HTTP method used for the request (GET by default).

• Expected status — the status code (or range) that counts as a successful check.

• Keyword — optional text that must appear in the response body.

• Timeout — how long to wait for a response before treating the check as failed.

• Confirm after — the number of consecutive failed checks required before an incident opens, to avoid false alarms from a single blip.

If a monitor uses HTTPS, PingTrail also tracks the certificate's expiry date and can warn you before it lapses.

Heartbeat monitors

A heartbeat monitor flips the direction of the check: instead of PingTrail requesting your system, your system pings PingTrail. This is ideal for cron jobs, queue workers, and scheduled scripts.

Create a heartbeat monitor to get a unique token, then call the following URL from the end of your job:

Set the expected interval and a grace period for the job. If a ping doesn't arrive within the grace period, the monitor is treated as late and can open an incident.

Multi-region probes

HTTP checks are distributed across probes, independent workers that can run in different regions. Spreading checks this way means a problem with a single network path or region doesn't look like a full outage.

Checks are staggered across probes so they don't all hit a monitor at the same instant, and an incident only opens once a monitor fails its configured number of consecutive checks.

Notification channels

Notification channels decide where alerts go. PingTrail currently supports:

• Email — send incident alerts to one or more addresses.

• Webhook — POST a JSON payload to a URL of your choice, so you can pipe incidents into chat tools, paging systems, or your own automation.

Attach a channel to any monitor, or share it across several. You'll be notified when an incident opens and again when it resolves.

Monitor groups

Groups let you organize monitors by product, environment, or team. Grouping monitors also powers public status pages: each group can have its own page, independent of the others.

Deploy markers

Tell PingTrail about your deploys and it draws them on each monitor's timeline. If an incident opens shortly after one, PingTrail notes it as a possible cause — never a verdict.

Issue a deploy token from a monitor group's page, then send a marker as the last step of your deploy:

The `|| true` and 5-second timeout mean a slow or unreachable PingTrail never fails your deploy.

Laravel Forge

Add the curl command above as the last line of the site's deploy script, and set MONITOR_TOKEN in the site's environment. git rev-parse works there because the deploy script runs inside the release directory.

GitHub Actions

Add a final step with if: always(), with the token stored as a repository secret:

`status` is optional (`started` or `finished`, defaulting to `finished`). Sending a `started` marker before the deploy and a `finished` marker after it defines a deploy window; a single `finished` marker also works, and so does a rollback — it's a deploy too.

Incidents & insights

When a monitor fails enough consecutive checks, PingTrail opens an incident and keeps a snapshot of the checks immediately before and after it started. This gives you the context to understand exactly what happened, down to the response codes and timings around the failure, without digging through raw logs.

Status pages

Every monitor group can publish a public status page showing current status and recent uptime history for its monitors. Each status page also exposes:

• An Atom feed, so subscribers can follow status changes in their feed reader.

• An embeddable SVG uptime badge you can drop into a README or docs site.

Status pages are public to anyone with the link, so only add monitors you're comfortable showing to the outside world.

Account security

From your account settings you can register a passkey for passwordless sign-in, or enable time-based two-factor authentication with recovery codes as a backup.

Getting help

Can't find what you're looking for? Reach out to support@pingtrail.dev and we'll help you out.