Understanding ping URLs

To determine the status of your cron job and heartbeat monitors, Cronitor must know when your jobs and tasks run and complete. To report these and other events, each monitor you create is given a unique ping URL with corresponding endpoints. A ping is a simple HTTP request with no payload that returns no content. Most commonly ping requests are made using curl and are completed in a fraction of a second.

Ping URL Endpoints

/run
/complete
/fail
/pause/{hours}

/run

"My Job Is Running"

Ping your /run endpoint to report that your task is running. In our cron monitoring example this is done by prepending the curl ping request to a job command directly within crontab. You may prefer to instrument your code itself with cronitor pings. Regardless of your specific implementation, you should always ping /run as closely as possible to the start of your job. Optionally send up to 2048 chars of context data as a url-encoded ?msg param.

Note: To support backwards compatibility, requests made to your ping URL without specifying an endpoint are treated as /run pings.

Note: Pings to the deprecated /b "begin" endpoint are treated as /run pings.

Pro Tips:
  • Use --data-urlencode to url encode your msg when using curl.
  • Your /run pings are used when evaluating Not On Schedule, Not Run In, Ran Longer Than, Ran Less Than, and Has Run rules.

/complete

"My Job Completed Successfully"

Ping your /complete endpoint to report that your task has completed successfully. In our cron monitoring example this is done by pinging Cronitor after the job has run successfully, using an && operator. You may prefer to instrument your code itself with cronitor pings. Regardless of your specific implementation, you should always ping /complete as closely as possible to the successful completion of your job. Optionally send up to 2048 chars of context data as a url-encoded ?msg param.

Pro Tips:
  • Use --data-urlencode to url encode your msg when using curl.
  • Your /complete pings are used when evaluating Not Completed In, Ran Longer Than, Ran Less Than, and Has Completed rules.

/fail

"My Job Has Failed"

Ping your /fail endpoint to report that your task has failed. In our cron monitoring example this is done by pinging Cronitor after the job exits with an error code, using an || operator. When a failure is reported you will be alerted immediately, without consideration to other rules. Optionally send up to 2048 chars of context data as a URL-encoded ?msg param.

Pro Tips:
  • Use --data-urlencode to url encode your msg when using curl.
  • After reporting a failure, Cronitor will temporarily suppress your Not Completed In and Ran Longer Than rules to avoid duplicate alerts.
  • Failure alert notifications are batched to one per minute.

/pause/{hours}

"No alerts should be sent for __ hours"

Ping your /pause endpoint to temporarily pause monitoring and alerts for this monitor. An {hours} integer is required. To unpause instantly, use "0" hours. After the pause expires you may receive an alert immediately if any of your rules are triggered.

Pro Tips:
  • You can permanently pause a monitor from your dashboard, or by specifying a large number of {hours}
  • Alert emails always include links to pause monitoring for an hour or day to prevent repeated alerts

Note: This endpoint is built for use from curl or a browser, and returns an HTML response. Clients can ignore the body and trust the response code.

Security and Privacy Concerns

Unlike our automation API, your ping URL endpoints do not require authentication by default. However, subscribers can opt-in to using an auth_key when making tracking requests or viewing their monitor's history.

To opt-in to using your auth_key go to your account settings page. Add the provided auth_key to your ping requests. Once all pings include the key, activate the checkbox that says "Authenticate monitor requests". Once you have enabled this feature any requests without a valid auth_key querystring parameter will be ignored.

  # Example using your auth_key to ping your monitor's complete endpoint
  curl -m 5 https://cronitor.link/d3x0c1/complete?auth_key=your_unique_auth_key

There are a few additional points on security and privacy to consider:

  • Always use SSL (eg https://). Cronitor supports unencrypted pings because some use-cases demand it, but unless yours is one, you should use SSL. Requests made using SSL are private: the URL is encrypted and protected in transit. As an added benefit, SSL prevents unwanted caching that could occur between your system and Cronitor.
  • While your unique ping URL might look like it's just a plain hash, there is an embedded checksum. This gives us the ability to detect and filter unwanted traffic. Even clever systems have vulnerabilities, but our security is enhanced by being an uninteresting target.

Shortened Endpoint Aliases

Every integration has constraints. If it's more important to be brief than explicit, you can use a 1 character abbreviated short form of each endpoint: /r, /c, /f and /p.

Accepted Methods

Ping endpoints will accept GET, POST and HEAD requests. At this time, all POST bodies are discarded.

Ping URLs on the cronitor.io hostname

Originally, ping URLs were hosted on the cronitor.io domain. To segregate ping traffic, we launched the cronitor.link domain in February, 2015. We plan to continue supporting ping requests on cronitor.io indefinitely but if you are currently pinging cronitor.io, you may experience faster ping times by switching to cronitor.link.

Pro Tip: Unencrypted (e.g. http://) pings are only accepted on cronitor.link. Unencrypted pings sent to cronitor.io will receive a 301 redirect response pointing to https://cronitor.io

Deprecated Endpoints

To more clearly align rules and endpoints, /b and /e ping endpoints are deprecated and will be mapped internally to /run and /complete, respectively. Similarly, you may have been given a URL without any endpoint specified. This URL was always treated as a /b "begin" ping. We've deprecated these requests and discourage them. To maintain backwards compatibility we will continue to map these requests to /run.

If you are an early Cronitor user with a "not run in" rule and you modify your integration to ping /run before your job and /complete after, you may want to change your "not run in" rules to "not completed in". A "not run in" rule uses /run pings, which you will now send before the job runs. A "not completed in" rule uses the /complete pings that will only be sent if your job completes successfully.