# docs_content

c0: javascript
c1: Javascript
c2:
Below is a minimal example of making an HTTP request to Mychecks from Node.js. Note: the "https" library executes requests asynchronously. If you send both "start" and "success" signals, you can encounter a race condition where the "success" signal arrives before the "start" signal. Avoid the race condition by using callbacks, promises or the async/await feature. Here is an example that uses async/await and the axios library: Browser You can also send pings from a browser environment. Mychecks sets the Access-Control-Allow-Origin:* CORS header, so cross-domain AJAX requests work.


c0: measuring_script_run_time
c1: Measuring Script Run Time
c2:
Append /start to a ping URL and use it to signal when a job starts. After receiving a start signal, Healthchecks.io will show the check as "Started." It will store the "start" events and display the job execution times. Mychecks calculates the job execution times as the time gaps between adjacent "start" and "success" events. Alerting Logic Mychecks applies an additional alerting rule for jobs that use the /start signal. If a job sends a "start" signal, but then does not send a "success" signal within its configured grace time, Mychecks will assume the job has failed. It will mark the job as "down" and send out alerts. Usage Example Below is a code example in Python: Viewing Measured Run Times When Mychecks receives a "start" signal followed by a regular ping or a "fail" signal, and the two events are less than 72 hours apart, you will see the duration displayed in the list of checks. If the two events are more than 72 hours apart, they are assumed to be unrelated, and the duration is not displayed. You can also see durations of the previous runs when viewing an individual check: Specifying Run IDs When several instances of the same job can run concurrently, the calculated run times can come out wrong, as Mychecks cannot reliably determine which success event corresponds to which start event. To work around this problem, the client can optionally specify a run ID in the rid query parameter of any ping URL. When a success event specifies the rid parameter, Mychecks will look for a start event with a matching rid value when calculating the execution time. The run IDs must be in a specific format: they must be UUID values in the canonical textual representation (example: 728b3763-ea80-4113-9fc0-f49b3adf226a, note no curly braces, and no uppercase characters). The client is free to pick run ID values randomly or use a deterministic process to generate them. The only thing that matters is that the start and the success pings of a single job execution use the same run ID value. Below is an example shell script which generates the run ID using uuidgen and makes HTTP requests using curl: If the client specifies run IDs, Mychecks will display them in the "Events" section in a shortened form: Also, note how the execution times are available for both "success" events. If the run IDs were not used in this example, the event #4 would not show an execution time since it is not preceded by a "start" event. Alerting Logic When Using Run IDs If a job sends a "start" signal, but then does not send a "success" signal within its configured grace time, Mychecks will assume the job has failed and notify you. However, when using Run IDs, there is an important caveat: Mychecks will not monitor the execution times of all concurrent job runs, it will only monitor the execution time of the most recently started run. To illustrate, let's assume the grace time of 1 minute, and look at the above example again. The event #4 ran for 6 minutes 39 seconds and so overshot the time budget of 1 minute. But Mychecks generated no alerts because the most recently started run completed within the time limit (it took 37 seconds, which is less than 1 minute).


c0: api
c1: Management API v3
c2:
Version: v1 v2 v3 With the Management API, you can programmatically manage checks and integrations in your account. API Endpoints Endpoint Name Endpoint Address Checks List existing checks GET http://localhost:8000/api/v3/checks/ Get a single check GET http://localhost:8000/api/v3/checks/<uuid>GET http://localhost:8000/api/v3/checks/<unique_key> Create a new check POST http://localhost:8000/api/v3/checks/ Update an existing check POST http://localhost:8000/api/v3/checks/<uuid> Pause monitoring of a check POST http://localhost:8000/api/v3/checks/<uuid>/pause Resume monitoring of a check POST http://localhost:8000/api/v3/checks/<uuid>/resume Delete check DELETE http://localhost:8000/api/v3/checks/<uuid> Pings List check's logged pings GET http://localhost:8000/api/v3/checks/<uuid>/pings/ Get a ping's logged body GET http://localhost:8000/api/v3/checks/<uuid>/pings/<n>/body Flips List check's status changes GET http://localhost:8000/api/v3/checks/<uuid>/flips/GET http://localhost:8000/api/v3/checks/<unique_key>/flips/ Integrations List existing integrations GET http://localhost:8000/api/v3/channels/ Badges List project's badges GET http://localhost:8000/api/v3/badges/ Changes From v2 Management API v3 adds the ability to specify custom check slugs, instead of auto-generating them from check names. The Create a new check and Update an existing check calls accept a new slug parameter, and use it instead of generating the slug from the check's name. Authentication Your requests to Mychecks Management API must authenticate using an API key. All API keys are project-specific. There are no account-wide API keys. By default, a project on Mychecks doesn't have an API key. You can create read-write and read-only API keys on the Project Settings page. read-write key Has full access to all documented API endpoints. read-only key Only works with the following API endpoints: List existing checks Get a single check List check's status changes List project's badges Omits sensitive information from the API responses. See the documentation of individual API endpoints for details. The client can authenticate itself by including an X-Api-Key: <your-api-key> header in an HTTP request. Alternatively, for POST requests with a JSON request body, the client can put an api_key field in the JSON document. See the Create a new check section for an example. API Requests For POST requests, the Mychecks API expects the request body to be a JSON document (not a multipart/form-data encoded form data). API Responses Mychecks uses HTTP status codes wherever possible. In general, 2xx class indicates success, 4xx indicates a client error, and 5xx indicates a server error. The response may contain a JSON document with additional data. List Existing Checks GET http://localhost:8000/api/v3/checks/ Returns a list of checks belonging to the user, optionally filtered by one or more tags. Query Parameters slug=<value> Filters the checks and returns only the checks with the specified slug. If there are no matching checks, returns an empty list. If there are multiple matching checks, returns all of them. Example: http://localhost:8000/api/v3/checks/?slug=backups tag=<value> Filters the checks and returns only the checks that are tagged with the specified value. This parameter can be repeated multiple times. Example: http://localhost:8000/api/v3/checks/?tag=foo&tag=bar Response Codes 200 OK The request succeeded. 401 Unauthorized The API key is either missing or invalid. Example Request Example Response The possible values for the status field are: new, up, grace, down, and paused. When using the read-only API key, Mychecks omits the following fields from responses: ping_url, update_url, pause_url, resume_url, channels. It adds an extra unique_key field. The unique_key identifier is stable across API calls, and you can use it in the Get a single check and List check's status changes API calls. Example: Get a Single Check GET http://localhost:8000/api/v3/checks/<uuid> GET http://localhost:8000/api/v3/checks/<unique_key> Returns a JSON representation of a single check. Accepts either check's UUID or the unique_key (a field derived from UUID and returned by API responses when using the read-only API key) as an identifier. Response Codes 200 OK The request succeeded. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Example Response The possible values for the status field are: new, up, grace, down, and paused. Example Read-Only Response When using the read-only API key, Mychecks omits the following fields from responses: ping_url, update_url, pause_url, resume_url, channels. It adds an extra unique_key field. This identifier is stable across API calls. Note: although API omits the *_url fields in read-only API responses, the client can easily construct these URLs themselves if they know the check's unique UUID. Create a Check POST http://localhost:8000/api/v3/checks/ Creates a new check and returns its ping URL. All request parameters are optional and will use their default values if omitted. With this API call, you can create both Simple and Cron checks: To create a Simple check, specify the timeout parameter. To create a Cron check, specify the schedule and tz parameters. Request Parameters name string, optional, default value: "" Name for the new check. Changed in API v3: the check's slug is no longer automatically generated from the check's name. Instead, the client can specify the slug explicitly via the slug field. slug string, optional, default value: "" Slug for the new check. The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. Example: tags string, optional, default value: "" A space-delimited list of tags for the new check. Example: desc string, optional. Description of the check. timeout number, optional, default value: 86400. The expected period of this check in seconds. Minimum: 60 (one minute), maximum: 31536000 (365 days). Example for a 5-minute timeout: grace number, optional, default value: 3600. The grace period for this check in seconds. Minimum: 60 (one minute), maximum: 31536000 (365 days). schedule string, optional, default value: "* * * * *". A cron expression defining this check's schedule. If you specify both timeout and schedule parameters, Mychecks will create a Cron check and ignore the timeout value. Example for a check running every half-hour: tz string, optional, default value: "UTC". Server's timezone. This setting only has an effect in combination with the schedule parameter. Example: manual_resume boolean, optional, default value: false. Controls whether a paused check automatically resumes when pinged (the default) or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard. methods string, optional, default value: "". Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST". Set this field to "" (an empty string) to allow HEAD, GET, and POST requests. Set this field to "POST" to allow only POST requests. Example: channels string, optional By default, this API call assigns no integrations to the newly created check. Set this field to a special value "*" to automatically assign all existing integrations. Example: To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call. Example: Alternatively, if you have named your integrations in Mychecks dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty unique names, and they must not contain commas. The names must match exactly, whitespace is significant. Example: unique array of string values, optional, default value: []. Enables "upsert" functionality. Before creating a check, Mychecks looks for existing checks, filtered by fields listed in unique. If Mychecks does not find a matching check, it creates a new check and returns it with the HTTP status code 201. If Mychecks finds a matching check, it updates the existing check and returns it with HTTP status code 200. The accepted values for the unique field are name, slug, tags, timeout, and grace. Example: In this example, if a check named "Backups" exists, it will be returned. Otherwise, a new check will be created and returned. start_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Start" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, Mychecks classifies the email as a start signal if the Subject line contains the word "STARTED". success_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED". failure_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR". filter_subject boolean, optional, default value: false. Enables filtering of inbound email messages by looking for keywords in their subject lines. See also the success_kw and failure_kw fields. filter_body boolean, optional, default value: false. Enables filtering of inbound email messages by looking for keywords in their message body. See also the success_kw and failure_kw fields. subject string, optional, default value: "". Deprecated. Use the success_kw, filter_subject and filter_body fields instead. Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Success". Set this field to "" (an empty string) to consider all inbound email messages as "Success" (unless they match any keywords listed in subject_fail and are thus classified as "Failure"). Example: In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED". subject_fail string, optional, default value: "". Deprecated. Use the failure_kw, filter_subject and filter_body fields instead. Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Failure". Set this field to "" (an empty string) to perform no "Failure" classification. Example: In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR". Response Codes 201 Created A new check was successfully created. 200 OK An existing check was found and updated. 400 Bad Request The request is not well-formed, violates schema, or uses invalid field values. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden The account has hit its check limit. For free accounts, the limit is 20 checks per account. Example Request Or, alternatively: Example Response Update an Existing Check POST http://localhost:8000/api/v3/checks/<uuid> Updates an existing check. All request parameters are optional. If you omit any parameter, Mychecks will leave its value unchanged. Request Parameters name string, optional. Name for the check. Changed in API v3: the check's slug is no longer automatically generated from the check's name. Instead, the client can specify the slug explicitly via the slug field. slug string, optional Slug for the new check. The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. Example: tags string, optional. A space-delimited list of tags for the check. Example: desc string, optional. Description of the check. timeout number, optional. The expected period of this check in seconds. Minimum: 60 (one minute), maximum: 31536000 (365 days). Example for a 5-minute timeout: grace number, optional. The grace period for this check in seconds. Minimum: 60 (one minute), maximum: 31536000 (365 days). schedule string, optional. A cron expression defining this check's schedule. If you specify both timeout and schedule parameters, Mychecks will save the schedule parameter and ignore the timeout. Example for a check running every half-hour: tz string, optional. Server's timezone. This setting only has an effect in combination with the "schedule" parameter. Example: manual_resume boolean, optional, default value: false. Controls whether a paused ping automatically resumes when pinged (the default), or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard. methods string, optional, default value: "". Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST". Set this field to "" (an empty string) to allow HEAD, GET, and POST requests. Set this field to "POST" to allow only POST requests. Example: channels string, optional. Set this field to a special value "*" to automatically assign all existing integrations. Example: Set this field to a special value "" (empty string) to automatically unassign all existing integrations. Example: To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call. Example: Alternatively, if you have named your integrations in Mychecks dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty and unique names, and they must not contain commas. The names must match exactly, whitespace is significant. Example: start_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Start" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, Mychecks classifies the email as a start signal if the Subject line contains the word "STARTED". success_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED". failure_kw string, optional, default value: "". Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. Use this field in combination with the filter_subject and filter_body fields. Setting filter_subject to true enables filtering on the email subject line, filter_body enables filtering on the entire email body. Mychecks supports both plain text and HTML email messages. Example: In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR". filter_subject boolean, optional, default value: false. Enables filtering of inbound email messages by looking for keywords in their subject lines. See also the success_kw and failure_kw fields. filter_body boolean, optional, default value: false. Enables filtering of inbound email messages by looking for keywords in their message body. See also the success_kw and failure_kw fields. subject string, optional, default value: "". Deprecated. Use the success_kw, filter_subject and filter_body fields instead. Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Success". Set this field to "" (an empty string) to consider all inbound email messages as "Success" (unless they match any keywords listed in subject_fail and are thus classified as "Failure"). Example: In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED". subject_fail string, optional, default value: "". Deprecated. Use the failure_kw, filter_subject and filter_body fields instead. Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Failure". Set this field to "" (an empty string) to perform no "Failure" classification. Example: In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR". Response Codes 200 OK The check was successfully updated. 400 Bad Request The request is not well-formed, violates schema, or uses invalid field values. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Or, alternatively: Example Response Pause Monitoring of a Check POST http://localhost:8000/api/v3/checks/<uuid>/pause Disables monitoring for a check without removing it. The check goes into a "paused" state. You can resume monitoring of the check by pinging it, or by running the Resume API call (useful when check's manual_resume=True). This API call has no request parameters. Response Codes 200 OK The check was successfully paused. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Note: the --data "" argument forces curl to send a Content-Length request header even though the request body is empty. For HTTP POST requests, the Content-Length header is sometimes required by some network proxies and web servers. Example Response Resume Monitoring of a Check POST http://localhost:8000/api/v3/checks/<uuid>/resume Resumes a check. The check goes into the "new" state. Use this API call to resume the monitoring of checks that are in the paused state, and have the manual_resume configuration parameter set to True. This API call has no request parameters. Response Codes 200 OK The operation was successful. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. 409 Conflict The specified check is currently not in a paused state. Example Request Note: the --data "" argument forces curl to send a Content-Length request header even though the request body is empty. For HTTP POST requests, the Content-Length header is sometimes required by some network proxies and web servers. Example Response Delete Check DELETE http://localhost:8000/api/v3/checks/<uuid> Permanently deletes the check from the user's account. Returns JSON representation of the check that was just deleted. This API call has no request parameters. Response Codes 200 OK The check was successfully deleted. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Example Response List check's logged pings GET http://localhost:8000/api/v3/checks/<uuid>/pings/ Returns a list of pings this check has received. This endpoint returns pings in reverse order (most recent first), and the total number of returned pings depends on the account's billing plan: 100 for free accounts, 1000 for paid accounts. Response Codes 200 OK The request succeeded. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Example Response Get a ping's logged body GET http://localhost:8000/api/v3/checks/<uuid>/pings/<n>/body Returns a ping's logged body. The response always has the Content-Type: text/plain response header and the ping body is returned verbatim in the response body. Response Codes 200 OK The request succeeded and a body is present. 403 Forbidden Access denied, wrong API key. 404 Not Found The check does not exist, the ping does not exist, or the ping has no body data. Example Request List check's status changes GET http://localhost:8000/api/v3/checks/<uuid>/flips/ GET http://localhost:8000/api/v3/checks/<unique_key>/flips/ Returns a list of "flips" this check has experienced. A flip is a change of status (from "down" to "up," or from "up" to "down"). Query Parameters seconds=<value> Returns the flips from the last value seconds Example: http://localhost:8000/api/v3/checks/<uuid|unique_key>/flips/?seconds=3600 start=<value> Returns flips that are newer than the specified UNIX timestamp. Example: http://localhost:8000/api/v3/checks/<uuid|unique_key>/flips/?start=1592214380 end=<value> Returns flips that are older than the specified UNIX timestamp. Example: http://localhost:8000/api/v3/checks/<uuid|unique_key>/flips/?end=1592217980 Response Codes 200 OK The request succeeded. 400 Bad Request Invalid query parameters. 401 Unauthorized The API key is either missing or invalid. 403 Forbidden Access denied, wrong API key. 404 Not Found The specified check does not exist. Example Request Example Response List Existing Integrations GET http://localhost:8000/api/v3/channels/ Returns a list of integrations belonging to the project. Response Codes 200 OK The request succeeded. 401 Unauthorized The API key is either missing or invalid. Example Request Example Response List Project's Badges GET http://localhost:8000/api/v3/badges/ Returns a map of all tags in the project, with badge URLs for each tag. Mychecks provides badges in a few different formats: svg: returns the badge as an SVG document. json: returns a JSON document which you can use to generate a custom badge yourself. shields: returns JSON in a Shields.io compatible format. In addition, badges have 2-state and 3-state variations: svg, json, shields: reports two states: "up" and "down". It considers any checks in the grace period as still "up". svg3, json3, shields3: reports three states: "up", "late", and "down". The response includes a special * entry: this pseudo-tag reports the overall status of all checks in the project. Response Codes 200 OK The request succeeded. 401 Unauthorized The API key is either missing or invalid. Example Request Example Response


c0: self_hosted_configuration
c1: Server Configuration
c2:
Healthchecks prepares its configuration in hc/settings.py. It reads configuration from environment variables. Below is a list of variables it reads and uses. ADMINS ALLOWED_HOSTS APPRISE_ENABLED DB DB_CONN_MAX_AGE DB_HOST DB_NAME DB_PASSWORD DB_PORT DB_SSLMODE DB_TARGET_SESSION_ATTRS DB_USER DEBUG DEFAULT_FROM_EMAIL DISCORD_CLIENT_ID DISCORD_CLIENT_SECRET EMAIL_HOST EMAIL_HOST_PASSWORD EMAIL_HOST_USER EMAIL_PORT EMAIL_USE_TLS EMAIL_USE_SSL EMAIL_USE_VERIFICATION http_proxy and https_proxy INTEGRATIONS_ALLOW_PRIVATE_IPS LINENOTIFY_CLIENT_ID LINENOTIFY_CLIENT_SECRET MASTER_BADGE_LABEL MATRIX_ACCESS_TOKEN MATRIX_HOMESERVER MATRIX_USER_ID MATTERMOST_ENABLED MSTEAMS_ENABLED OPSGENIE_ENABLED PAGERTREE_ENABLED PD_APP_ID PD_ENABLED PING_BODY_LIMIT PING_EMAIL_DOMAIN PING_ENDPOINT PROMETHEUS_ENABLED PUSHBULLET_CLIENT_ID PUSHBULLET_CLIENT_SECRET PUSHOVER_API_TOKEN PUSHOVER_EMERGENCY_EXPIRATION PUSHOVER_EMERGENCY_RETRY_DELAY PUSHOVER_SUBSCRIPTION_URL REGISTRATION_OPEN REMOTE_USER_HEADER ROCKETCHAT_ENABLED RP_ID S3_ACCESS_KEY S3_BUCKET S3_ENDPOINT S3_REGION S3_SECRET_KEY S3_TIMEOUT SECRET_KEY SHELL_ENABLED SIGNAL_CLI_SOCKET SITE_LOGO_URL SITE_NAME SITE_ROOT SLACK_CLIENT_ID SLACK_CLIENT_SECRET SLACK_ENABLED SPIKE_ENABLED TELEGRAM_BOT_NAME TELEGRAM_TOKEN TRELLO_APP_KEY TWILIO_ACCOUNT TWILIO_AUTH TWILIO_FROM TWILIO_MESSAGING_SERVICE_SID TWILIO_USE_WHATSAPP USE_PAYMENTS VICTOROPS_ENABLED WEBHOOKS_ENABLED ZULIP_ENABLED ADMINS Default: "" (empty string) A comma-sepparated list of email addresses to send code error notifications to. When DEBUG=False, Healthchecks will send the details of exceptions raised in the request/response cycle to the listed addresses. Example: Note: for error notifications to work, make sure you have also specified working SMTP credentials in the EMAIL_... environment variables. ALLOWED_HOSTS Default: * The host/domain names that this site can serve. You can specify multiple domain names by separating them with commas: Apart from the comma-separated syntax, this is a standard Django setting. Read more about it in the Django documentation. APPRISE_ENABLED Default: False A boolean that turns on/off the Apprise integration. Before enabling the Apprise integration, make sure the apprise package is installed: DB Default: sqlite The database engine to use. Possible values: sqlite, postgres, mysql. DB_CONN_MAX_AGE Default: 0 This is a standard Django setting, read more in Django documentation. DB_HOST Default: "" (empty string) This is a standard Django setting, read more in Django documentation. DB_NAME Default: hc (PostgreSQL, MySQL) or /path/to/projectdir/hc.sqlite (SQLite) This is a standard Django setting, read more in Django documentation. DB_PASSWORD Default: "" (empty string) This is a standard Django setting, read more in Django documentation. DB_PORT Default: "" (empty string) This is a standard Django setting, read more in Django documentation. DB_SSLMODE Default: prefer PostgreSQL-specific, details DB_TARGET_SESSION_ATTRS Default: read-write PostgreSQL-specific, details DB_USER Default: postgres (PostgreSQL) or root (MySQL) This is a standard Django setting, read more in Django documentation. DEBUG Default: True A boolean that turns on/off debug mode. Never run a Healthchecks instance in production with the debug mode turned on! This is a standard Django setting, read more in Django documentation. DEFAULT_FROM_EMAIL Default: healthchecks@example.org This is a standard Django setting, read more in Django documentation. DISCORD_CLIENT_ID Default: None The Discord Client ID, required by the Discord integration. To set up the Discord integration: Register a new application at https://discordapp.com/developers/applications/me Add a Redirect URI to your Discord application. The URI format is SITE_ROOT/integrations/add_discord/. For example, if your SITE_ROOT is https://my-hc.example.org then the Redirect URI would be https://my-hc.example.org/integrations/add_discord/ Look up your Discord app's Client ID and Client Secret. Put them in the DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET environment variables. DISCORD_CLIENT_SECRET Default: None The Discord Client Secret, required by the Discord integration. Look it up at https://discordapp.com/developers/applications/me. EMAIL_HOST Default: "" (empty string) This is a standard Django setting, read more in Django documentation. EMAIL_HOST_PASSWORD Default: "" (empty string) This is a standard Django setting, read more in Django documentation. EMAIL_HOST_USER Default: "" (empty string) This is a standard Django setting, read more in Django documentation. EMAIL_PORT Default: 587 This is a standard Django setting, read more in Django documentation. EMAIL_USE_TLS Default: True This is a standard Django setting, read more in Django documentation. EMAIL_USE_SSL Default: False This is a standard Django setting, read more in Django documentation. EMAIL_USE_VERIFICATION Default: True A boolean that turns on/off a verification step when adding an email integration. If enabled, whenever a user adds an email integration, Healthchecks emails a verification link to the new address. The new integration becomes active only after the user clicks the verification link. If you are setting up a private healthchecks instance where you trust your users, you can opt to disable the verification step. In that case, set EMAIL_USE_VERIFICATION to False. http_proxy and https_proxy Default: "" (empty string) Specifies the proxy server to use for outgoing HTTP and HTTPS requests. Supports different proxy server types. Examples: Healthchecks uses libcurl as the HTTP client library for making HTTP(S) requests. For more information about the proxy functionality, please see libcurl documentation. Note: If your proxy server has a private IP address, you will also need to set the INTEGRATIONS_ALLOW_PRIVATE_IPS setting to True to use it. INTEGRATIONS_ALLOW_PRIVATE_IPS Default: False A boolean that controls whether the integrations are allowed to make HTTP(S) requests to private IP addresses (127.0.0.1, 192.168.x.x, ...). This setting is set to False by default, because allowing users to define webhooks that probe internal addresses is a security risk. Only enable this setting if you run your Healthchecks instance in a trusted environment, and need to integrate with services running in your internal network. This setting affects all integration types, not just webhooks. For example, if you run a Gotify instance on localhost, you will need to enable INTEGRATIONS_ALLOW_PRIVATE_IPS to be able to use it via the Gotify integration. This setting affects all outbound HTTP requests, including those made while setting up new integrations (e.g. during the OAuth2 authorization flow). This setting also affects connections to the proxy server when the http_proxy or https_proxy environment variables are set. If your proxy server has a private IP address, you will need to enable INTEGRATIONS_ALLOW_PRIVATE_IPS to use it. LINENOTIFY_CLIENT_ID Default: None LINENOTIFY_CLIENT_SECRET Default: None MASTER_BADGE_LABEL Default: same as SITE_NAME The label for the "Overall Status" status badge. MATRIX_ACCESS_TOKEN Default: None The Matrix bot user's access token, required by the Matrix integration. To set up the Matrix integration: Register a bot user (for posting notifications) in your preferred Matrix homeserver. Use the Login API call to retrieve bot user's access token. You can run it as shown in the documentation, using curl in the command shell. Set the MATRIX_ environment variables. Example: MATRIX_HOMESERVER Default: None The Matrix bot's homeserver address, required by the Matrix integration. MATRIX_USER_ID Default: None The Matrix bot's user identifier, required by the Matrix integration. MATTERMOST_ENABLED Default: True A boolean that turns on/off the Mattermost integration. Enabled by default. MSTEAMS_ENABLED Default: True A boolean that turns on/off the MS Teams integration. Enabled by default. OPSGENIE_ENABLED Default: True A boolean that turns on/off the Opsgenie integration. Enabled by default. PAGERTREE_ENABLED Default: True A boolean that turns on/off the PagerTree integration. Enabled by default. PD_APP_ID Default: None PagerDuty application ID. If set, enables the PagerDuty Simple Install Flow. If None, Healthchecks will fall back to the even simpler flow where users manually copy integration keys from PagerDuty and paste them in Healthchecks. To set up: Register a PagerDuty app at PagerDuty › Developer Mode › My Apps In the newly created app, add the "Events Integration" functionality Specify a Redirect URL: https://your-domain.com/integrations/add_pagerduty/ Copy the displayed app_id value (PXXXXX) and put it in the PD_APP_ID environment variable PD_ENABLED Default: True A boolean that turns on/off the PagerDuty integration. Enabled by default. PING_BODY_LIMIT Default: 10000 The upper size limit in bytes for logged ping request bodies. The default value is 10000 (10 kilobytes). You can adjust the limit or you can remove it altogether by setting this value to None. PING_EMAIL_DOMAIN Default: localhost The domain to use for generating ping email addresses. Example: In this example, Healthchecks would generate ping email addresses similar to 3f1a7317-8e96-437c-a17d-b0d550b51e86@ping.my-hc.example.org. PING_ENDPOINT Default: SITE_ROOT + /ping/ The base URL to use for generating ping URLs. Example: In this example, Healthchecks would generate ping URLs similar to https://ping.my-hc.example.org/3f1a7317-8e96-437c-a17d-b0d550b51e86. PROMETHEUS_ENABLED Default: True A boolean that turns on/off the Prometheus integration. Enabled by default. PUSHBULLET_CLIENT_ID Default: None The Pushbullet Client ID, required by the Pushbullet integration. To set up the Pushbullet integration: Add a new OAuth client at https://www.pushbullet.com/#settings/clients Add a redirect_uri to your OAuth client. The URI format is SITE_ROOT/integrations/add_pushbullet/. For example, if your SITE_ROOT is https://my-hc.example.org then the redirect_uri would be https://my-hc.example.org/integrations/add_pushbullet/ Look up your OAuth client's client_id and client_secret values. Put them in the PUSHBULLET_CLIENT_ID and PUSHBULLET_CLIENT_SECRET environment variables. Read more about setting up a Pushbullet OAuth client in the Pushbullet OAuth2 guide. PUSHBULLET_CLIENT_SECRET Default: None The Pushbullet Client Secret, required by the Pushbullet integration. Look it up at https://www.pushbullet.com/#settings/clients. PUSHOVER_API_TOKEN Default: None The Pushover API token, required by the Pushover integration. To enable the Pushover integration: Register a new Pushover application at https://pushover.net/apps/build. Within the Pushover application configuration, enable subscriptions. Make sure the subscription type is set to "URL". Also make sure the redirect URL is configured to point back to the root of the Healthchecks instance (e.g., https://my-hc.example.org/). Put the Pushover application's API Token and the Subscription URL in PUSHOVER_API_TOKEN and PUSHOVER_SUBSCRIPTION_URL environment variables. The Pushover subscription URL should look similar to https://pushover.net/subscribe/yourAppName-randomAlphaNumericData. PUSHOVER_EMERGENCY_EXPIRATION Default: 86400 (24 hours) Specifies how many seconds an emergency Pushover notification will continue to be retried for. More information in Pushover API documentation. PUSHOVER_EMERGENCY_RETRY_DELAY Default: 300 (5 minutes) Specifies how often (in seconds) the Pushover servers will send the same notification to the user. More information in Pushover API documentation. PUSHOVER_SUBSCRIPTION_URL Default: None The Pushover Subscription URL, required by the Pushover integration. REGISTRATION_OPEN Default: True A boolean that controls whether site visitors can create new accounts. Set it to False if you are setting up a private Healthchecks instance, but it needs to be publicly accessible (so, for example, your cloud services can send pings to it). If you close new user registration, you can still selectively invite users to your team account. REMOTE_USER_HEADER Default: None Specifies the request header to use for external authentication. If you use a reverse proxy that handles user authentication, and the reverse proxy can pass the authenticated user's email address in an HTTP request header, you can use this setting to integrate Healthchecks with it. When REMOTE_USER_HEADER is set, Healthchecks will: in views that require authentication, look up the request header specified in REMOTE_USER_HEADER assume the header contains the user's email address automatically log in the user with a matching email address automatically create a user account if it does not exist disable the default authentication methods (login link to email, password) The header name in REMOTE_USER_HEADER must be specified in upper-case, with any dashes replaced with underscores, and prefixed with HTTP_. For example, if your authentication proxy sets a X-Authenticated-User request header, you should set REMOTE_USER_HEADER=HTTP_X_AUTHENTICATED_USER. Important: When this option is enabled, Healtchecks will trust the header's value implicitly, so it is very important to ensure that attackers cannot set the value themselves (and thus impersonate any user). How to do this varies by your chosen proxy, but generally involves configuring it to strip out headers that normalize to the same name as the chosen identity header. ROCKETCHAT_ENABLED Default: True A boolean that turns on/off the Rocket.Chat integration. Enabled by default. RP_ID Default: None The Relying Party identifier, required by the WebAuthn second-factor authentication feature. Healthchecks optionally supports two-factor authentication using the WebAuthn standard. To enable WebAuthn support, set the RP_ID setting to a non-null value. Set its value to your site's domain without scheme and without port. For example, if your site runs on https://my-hc.example.org, set RP_ID to my-hc.example.org. Note that WebAuthn requires HTTPS, even if running on localhost. To test WebAuthn locally with a self-signed certificate, you can use the runsslserver command from the django-sslserver package. S3_ACCESS_KEY Default: None Access key of an account in S3 service. Healthchecks can optionally upload ping request body data to S3-compatible object storage instead of storing it in the database. To use this feature, provide valid credentials to an S3-compatible service by setting the following environment variables: S3_ACCESS_KEY (example: AKIAFIXMEFIXME) S3_BUCKET (example: my-bucket) S3_ENDPOINT (example: s3.eu-central-1.amazonaws.com) S3_REGION (example: eu-central-1) S3_SECRET_KEY S3_BUCKET Default: None Name of the bucket in S3 service for storing ping request body data. S3_ENDPOINT Default: None URL to the S3-compatible service. S3_REGION Default: None Region name of buckets in S3 service. S3_SECRET_KEY Default: None The secret key of an account in S3 service. S3_TIMEOUT Default: 60 Timeout for individual S3 operations, in seconds. SECRET_KEY Default: --- A secret key used for cryptographic signing. Should be set to a unique, unpredictable value. This is a standard Django setting, read more in Django documentation. SHELL_ENABLED Default: False A boolean that turns on/off the "Shell Commands" integration. The "Shell Commands" integration runs user-defined local shell commands when checks go up or down. This integration is disabled by default and can be enabled by setting the SHELL_ENABLED environment variable to True. Note: be careful when using "Shell Commands" integration, and only enable it when you fully trust the users of your Healthchecks instance. The commands will be executed by the manage.py sendalerts process and will run with its system permissions. SIGNAL_CLI_SOCKET Default: None The path to the signal-cli UNIX socket, or the hostname:port of the signal-cli TCP socket. Example (UNIX socket): Example (TCP socket): Healthchecks uses signal-cli to send Signal notifications. Healthcecks interacts with signal-cli over UNIX or TCP socket (requires signal-cli 0.10.0 or later). To enable the Signal integration: Set up and configure signal-cli to expose JSON RPC on an UNIX or TCP socket (instructions). Example: signal-cli -a +xxxxxx daemon --socket /tmp/signal-cli-socket Put the socket's location in the SIGNAL_CLI_SOCKET environment variable. SITE_LOGO_URL Default: None An URL pointing to the image you want to use as the site logo. If not set, Healthchecks will use a fallback image: /static/img/logo.png. You can place a custom logo in /static/img/, run manage.py collectstatic, and point SITE_LOGO_URL to it like so: Or you can serve the logo from another server, and point to it using an absolute URL: Either way, Healthchecks will use the provided SITE_LOGO_URL value as-is in HTML pages, and you should use an URL that the end user's browser will be able to access directly. The logo image can use any image format supported by browsers (PNG, SVG, JPG are all fine). Docker note. You can build a custom Docker image with your logo "baked in". To do so, use a Dockerfile with the following contents, and with your logo.png placed next to it: This overwrites the default placeholder logo, so, in this case, you do not need to specify SITE_LOGO_URL. Notice that the logo must be placed in static-collected, not static. This is because manage.py collectstatic has already been run in the base image's build time, and the web server will not recognize any new files placed in the static directory. Please do not use the Healthchecks.io logo (the one with the dark green background) on self-hosted instances. This logo is not part of the Healthchecks open-source project. SITE_NAME Default: Mychecks The display name of this Healthchecks instance. Healthchecks uses it throughout its web UI and documentation. SITE_ROOT Default: http://localhost:8000 The base URL of this Healthchecks instance. Healthchecks uses SITE_ROOT whenever it needs to construct absolute URLs. SLACK_CLIENT_ID Default: None The Slack Client ID, used by the Slack integration. The Slack integration can work with or without the Slack Client ID. If the Slack Client ID is not set, in the "Integrations - Add Slack" page, Healthchecks will ask the user to provide a webhook URL for posting notifications. If the Slack Client is set, Healthchecks will use the OAuth2 flow to get the webhook URL from Slack. The OAuth2 flow is more user-friendly. To set it up, go to https://api.slack.com/apps/ and create a Slack app. When setting up the Slack app, make sure to: Add the incoming-webhook scope to the Bot Token Scopes. Add a Redirect URL in the format SITE_ROOT/integrations/add_slack_btn/. For example, if your SITE_ROOT is https://my-hc.example.org then the Redirect URL would be https://my-hc.example.org/integrations/add_slack_btn/. SLACK_CLIENT_SECRET Default: None The Slack Client Secret. Required if SLACK_CLIENT_ID is set. Look it up at https://api.slack.com/apps/. SLACK_ENABLED Default: True A boolean that turns on/off the Slack integration. Enabled by default. SPIKE_ENABLED Default: True A boolean that turns on/off the Spike.sh integration. Enabled by default. TELEGRAM_BOT_NAME Default: ExampleBot The Telegram bot name, required by the Telegram integration. To set up the Telegram integration: Create a Telegram bot by talking to the BotFather. Set the bot's name, description, user picture, and add a "/start" command. After creating the bot you will have the bot's name and token. Put them in TELEGRAM_BOT_NAME and TELEGRAM_TOKEN environment variables. Run the settelegramwebhook management command. This command tells Telegram where to forward channel messages by invoking Telegram's setWebhook API call: For this to work, your SITE_ROOT must be publicly accessible and use the "https://" scheme. TELEGRAM_TOKEN Default: None The Telegram bot user's authentication token, required by the Telegram integration. TRELLO_APP_KEY Default: None The Trello app key, required by the Trello integration. To set up the Trello integration, get a developer API key from https://trello.com/app-key and put it in the TRELLO_APP_KEY environment variable. TWILIO_ACCOUNT Default: None Twilio Account SID, required by the SMS, Call, and WhatsApp integrations. TWILIO_AUTH Default: None Twilio Auth token, required by the SMS, Call, and WhatsApp integrations. TWILIO_FROM Default: None The Twilio phone number to use as the sender for SMS and WhatsApp notifications, and as the caller for Call integrations. Example: TWILIO_MESSAGING_SERVICE_SID Default: None Optional, the Twilio Messaging Service SID for sending SMS and WhatsApp notifications. If TWILIO_MESSAGING_SERVICE_SID is specified, Healthchecks will include it in the "MessagingServiceSid" field when sending SMS and WhatsApp messages via Twilio API. This will result in Twilio using a Messaging Service instead of a plain sender number to deliver the SMS and WhatsApp messages. If TWILIO_MESSAGING_SERVICE_SID is not set, Healthchecks will fall back to using the "From" field with the value configured in TWILIO_FROM in API requests. Example: TWILIO_USE_WHATSAPP Default: False A boolean that turns on/off the WhatsApp integration. USE_PAYMENTS Default: False A boolean that turns on/off billing features. VICTOROPS_ENABLED Default: True A boolean that turns on/off the Splunk On-Call (VictorOps) integration. Enabled by default. WEBHOOKS_ENABLED Default: True A boolean that turns on/off the Webhooks integration. Enabled by default. ZULIP_ENABLED Default: True A boolean that turns on/off the Zulip integration. Enabled by default.


c0: configuring_prometheus
c1: Configuring Prometheus
c2:
Mychecks supports exporting metrics and check statuses to Prometheus, for use with Grafana. You can generate the metrics export endpoint by going to your project settings and creating a read-only API key. You will then see the link to the Prometheus endpoint: Update the prometheus.yml You can copy the Prometheus endpoint URL and add it to the Prometheus configuration: Notice how we split up the URL and paste in the scheme, domain, and path separately. Reload Prometheus, and your changes should be live, coming in under the hc_ prefix. Available Metrics The Prometheus metrics endpoint exports the following metrics: hc_check_up For every check, indicates whether the check is currently up (1 for yes, 0 for no). Labels: name – name of the check tags – check's tags as a text string, multiple tags are delimited with spaces unique_key – a stable, unique identifier of the check (derived from check's code) hc_check_started For every check, indicates whether the check is currently running (1 for yes, 0 for no). Labels: name – name of the check tags – check's tags as a text string, multiple tags are delimited with spaces unique_key – a stable, unique identifier of the check (derived from check's code) hc_tag_up For every tag, indicates whether all checks with this tag are up (1 for yes, 0 for no). Labels: tag – name of the tag hc_checks_total The total number of checks. hc_checks_down_total The number of checks currently down. Constructing URLs to Check Details Pages You can use the unique_key labels to construct URLs to check's details pages in Mychecks. Construct the URLs like so:


c0: signaling_failures
c1: Signaling failures
c2:
You can actively signal a failure to Mychecks by slightly changing the ping URL: append either /fail or /{exit-status} to your normal ping URL. The exit status should be a 0-255 integer. Mychecks will interpret exit status 0 as success and all non-zero values as failures. Examples: By actively signaling failures to Mychecks, you can minimize the delay from your monitored service encountering a problem to you getting notified about it. Shell Scripts The below shell script appends $? (a special variable that contains the exit status of the last executed command) to the ping URL: Python Below is a skeleton code example in Python which signals a failure when the work function returns an unexpected value or throws an exception:


c0: email
c1: Email
c2:
As an alternative to HTTP/HTTPS requests, you can "ping" checks by sending email messages to special email addresses. By default, Mychecks will consider any email received at the displayed address as a "success" signal. You can also configure Mychecks to look for specific keywords in the subject line or the message body to decide if the message is a "start", a "success" or a "failure" signal. You can set up the keywords in the Filtering Rules dialog: Use Case: Newsletter Delivery Monitoring Consider a cron job that runs weekly and sends weekly newsletters to a list of email addresses. You have already set up a check to get alerted when your cron job fails to run. But what you ultimately want to check is if your emails are getting sent and delivered. The solution: set up another check, and add its email address to your list of recipient email addresses. Set its Period to 1 week. As long as your weekly email script runs correctly, and there are no email delivery issues, Mychecks will regularly receive an email, and the check will stay up. Email Delivery Delays Emails are more susceptible to random delivery delays than HTTP requests. You may need to increase the grace time parameter for your checks to account for the possible email delivery delays, and avoid false alerts. Tracking job durations (using the "start" and "success" signals) will be less accurate when pinging via email, and may not be feasible at all for jobs with very short durations.


c0: badges
c1: Status Badges
c2:
Mychecks provides status badges that you can embed them in your READMEs, internal dashboards or public status pages. Each Mychecks badge reports the combined status of checks tagged with a particular tag. There is also a catch-all badge which reflects the status of all checks in a project. The badges have public, but hard-to-guess URLs. Badges do not expose any information other than the badge label, and the aggregate status of their corresponding checks. It is not possible to reverse-engineer ping URLs from badge URLs. Badge States Each badge can be in one of the following three states: up (green) – all matching checks are up. late (orange) – at least one check is running late (but has not exceeded its grace time yet). down (red) – at least one check is currently down. By default, Mychecks displays badge URLs that report only the up and down states (and treat late as up). Using the "Badge states" button, you can switch to alternate URLs that report all three states. Badge Formats Mychecks offers badges in three different formats: SVG: returns an SVG document that you can use directly in an <img> element, or in a Markdown document. JSON: returns the badge label and the current status as a JSON document. Use this if you want to render the badge yourself. This can also serve as an integration point with a hosted status page: instruct your status page provider to monitor the badge URL, and look for the keyword "up" in the returned data. Shields.io: returns the badge label and the current status as a Shields.io-compatible JSON document. See Shields.io documentation on how to use it. The main benefit of using Shields.io to generate the badges is the extra visual styles and customization options that Shields.io supports. Badge for a Single Check If you need a status badge for a specific check, assign the check a unique tag. Then use that tag's badge.


c0: http_api
c1: Pinging API
c2:
With the Pinging API, you can signal success, start, failure, and log events from your systems. General Notes All ping endpoints support: HTTP and HTTPS HTTP 1.0, HTTP 1.1 and HTTP 2 IPv4 and IPv6 HEAD, GET, and POST request methods. For HTTP POST requests, clients can optionally include diagnostic information in the request body. If the request body looks like a UTF-8 string, Mychecks stores the request body (limited to the first 100 kB for each received ping). Successful responses will have the "200 OK" HTTP response status code and a short "OK" string in the response body. UUIDs and Slugs Each Pinging API request needs to uniquely identify a check. Mychecks supports two ways of identifying a check: by check's UUID, or by a combination of project's Ping Key and check's slug. Check's UUID is automatically assigned when the check is created. It is immutable. You cannot replace the automatically assigned UUID with a manually chosen one. When you delete a check, you also lose its UUID and cannot get it back. You can look up UUIDs of your checks in web UI or via Management API calls. Check's slug can be chosen by the user. The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. A common practice is to derive the slug from the check's name (for example, a check named "Database Backup" might have a slug "database-backup"), but the user is free to pick arbitrary slug values. Check's slug can be changed by the user, from the web interface or by using Management API calls. Check's slug is not guaranteed to be unique. If you make a Pinging API request using a non-unique slug, Mychecks will return the "409 Conflict" HTTP status code and ignore the request. Slug URLs optionally support auto-provisioning: if you make a Pinging API request to a slug with no corresponding check, Mychecks will create the check automatically. Auto-provisioning is off by default, to enable it, add a create=1 query parameter to the ping URL. Endpoints Endpoint Name Endpoint Address Success (UUID) http://localhost:8000/ping/<uuid> Start (UUID) http://localhost:8000/ping/<uuid>/start Failure (UUID) http://localhost:8000/ping/<uuid>/fail Log (UUID) http://localhost:8000/ping/<uuid>/log Report script's exit status (UUID) http://localhost:8000/ping/<uuid>/<exit-status> Success (slug) http://localhost:8000/ping/<ping-key>/<slug> Start (slug) http://localhost:8000/ping/<ping-key>/<slug>/start Failure (slug) http://localhost:8000/ping/<ping-key>/<slug>/fail Log (slug) http://localhost:8000/ping/<ping-key>/<slug>/log Report script's exit status (slug) http://localhost:8000/ping/<ping-key>/<slug>/<exit-status> Send a "success" Signal Using UUID Signals to Mychecks that the job has completed successfully (or, a continuously running process is still running and healthy). Mychecks identifies the check by the UUID value included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 404 not found Could not find a check with the specified UUID. Example Send a "start" Signal Using UUID Sends a "job has started!" message to Mychecks. Sending a "start" signal is optional, but it enables a few extra features: Mychecks will measure and display job execution times Mychecks will detect if the job runs longer than its configured grace time Mychecks identifies the check by the UUID value included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding completion ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 404 not found Could not find a check with the specified UUID. Example Send a "failure" Signal Using UUID Signals to Mychecks that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert. Mychecks identifies the check by the UUID value included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 404 not found Could not find a check with the specified UUID. Example Send a "log" Signal Using UUID Sends logging information to Mychecks without signaling success or failure. Mychecks will log the event and display it in check's "Events" section with the "Log" label. The check's status will not change. Mychecks identifies the check by the UUID value included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters rid=<uuid> Optional, specifies a run ID of this ping. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 404 not found Could not find a check with the specified UUID. Example Report Script's Exit Status (Using UUID) Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. Mychecks interprets 0 as a success and all other values as a failure. Mychecks identifies the check by the UUID value included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 400 invalid url format The URL does not match the expected format. 404 not found Could not find a check with the specified UUID. Example Send a "success" Signal (Using Slug) Signals to Mychecks that the job has completed successfully (or, a continuously running process is still running and healthy). Mychecks identifies the check by project's ping key and check's slug included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters create=0|1 Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Mychecks creates a new check automatically. Example: create=1 rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 201 Created A new check was automatically created, the request succeeded. 404 not found Could not find a check with the specified ping key and slug combination. 409 ambiguous slug Ambiguous, the slug matched multiple checks. Example Send a "start" Signal (Using Slug) Sends a "job has started!" message to Mychecks. Sending a "start" signal is optional, but it enables a few extra features: Mychecks will measure and display job execution times Mychecks will detect if the job runs longer than its configured grace time Mychecks identifies the check by project's ping key and check's slug included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters create=0|1 Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Mychecks creates a new check automatically. Example: create=1 rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding completion ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 201 Created A new check was automatically created, the request succeeded. 404 not found Could not find a check with the specified ping key and slug combination. 409 ambiguous slug Ambiguous, the slug matched multiple checks. Example Send a "failure" Signal (Using slug) Signals to Mychecks that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert. Mychecks identifies the check by project's ping key and check's slug included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters create=0|1 Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Mychecks creates a new check automatically. Example: create=1 rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 201 Created A new check was automatically created, the request succeeded. 404 not found Could not find a check with the specified ping key and slug combination. 409 ambiguous slug Ambiguous, the slug matched multiple checks. Example Send a "log" Signal (Using slug) Sends logging information to Mychecks without signaling success or failure. Mychecks will log the event and display it in check's "Events" section with the "Log" label. The check's status will not change. Mychecks identifies the check by project's ping key and check's slug included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters create=0|1 Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Mychecks creates a new check automatically. Example: create=1 rid=<uuid> Optional, specifies a run ID of this ping. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 201 Created A new check was automatically created, the request succeeded. 404 not found Could not find a check with the specified ping key and slug combination. 409 ambiguous slug Ambiguous, the slug matched multiple checks. Example Report Script's Exit Status (Using Slug) Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. Mychecks interprets 0 as a success and all other values as a failure. Mychecks identifies the check by project's ping key and check's slug included in the URL. The response may optionally contain a Ping-Body-Limit: <n> response header. If this header is present, its value is an integer, and it specifies how many bytes from the request body Mychecks will store per request. For example, if n=100, but the client sends 123 bytes in the request body, Mychecks will store the first 100 bytes, and ignore the remaining 23. The client can use this header to decide how much data to send in the request bodies of subsequent requests. Query Parameters create=0|1 Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Mychecks creates a new check automatically. Example: create=1 rid=<uuid> Optional, specifies a run ID of this ping. If run ID is specified, Mychecks uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: rid=123e4567-e89b-12d3-a456-426614174000. Response Codes 200 OK The request succeeded. 201 Created A new check was automatically created, the request succeeded. 400 invalid url format The URL does not match the expected format. 404 not found Could not find a project matching the specified ping key. 409 ambiguous slug Ambiguous, the slug matched multiple checks. Example


c0: cloning_checks
c1: Cloning Checks
c2:
You can clone individual checks from the "Check Details" page: The "Create a Copy..." function creates a new check in the same project and copies over the following: Name, tags, description Schedule Assigned notification methods The newly created check has a different ping URL, and it starts with an empty log. Cloning All Checks Into a New Project It is sometimes useful to clone an entire project. For example, when recreating an existing deployment in a new region. The Mychecks web interface does not have a function to clone an entire project, but you can clone all checks in the project relatively easily using the Management API calls. Below is an example using Python and the requests library:


c0: projects_teams
c1: Projects and Teams
c2:
Use Projects to organize checks in your Mychecks account. Your account initially has a single default project. You can create additional projects and transfer your checks between them as your usage grows. Checks and integrations are project-scoped: each check and each configured integration always belongs to a particular project. Checks can be transferred between projects. The transfer operation preserves check's ping address: Team Access You can grant your colleagues access to a project by inviting them into the project's team. Each project has its separate team, so you can grant access selectively. Inviting team members is more convenient and more secure than sharing a password to a single account. The user who created the project is listed as Owner. When you invite a user to the project, you can select one of the three roles for their membership: Team Member (what you usually want), Manager or Read-only. Team Members can: create, edit and remove checks create and remove integrations rename the project view and regenerate project's API keys give up their membership (from their Account Settings page) Team Members can not: invite new members to the project change project's owner manage project owner's billing settings remove the project Managers have the same permissions as Team Members, with one exception: Managers can invite new members and remove existing members from the project's team. Managers still can not change or remove the project's owner, or manage billing. Read-only members can: view checks, including check details and ping logs view integrations give up their membership Read-only members can not modify checks, integrations, or project settings. They also cannot access the project's API keys, as that would effectively give them read-write access through API. Projects and Check Limits Check Limit is the total number of checks your account can have. The specific limit depends on the account's billing plan. When you reach the Check Limit, you will not be able to create new checks. All projects owned by your account shares your account's Check Limit. For example, consider a Business account with two projects, "Project A" and "Project B." If A has 70 checks, then B cannot have more than 30 checks in order to not exceed the Business account's total limit of 100. However, only checks from your own projects count towards your account's quota. If you get invited to somebody else's project, that does not change the number of checks you can create in your projects. Projects and Team Size Limits Team Size is the number of unique users you can invite to your projects. Same as with Check Limit, all projects share your account's Team Size limit. However, if you invite the same user (using the same email address) into multiple projects, it only takes up a single seat. Projects and Monthly Reports Mychecks sends periodic email reports with a summary of checks from all your projects. The reports contain status summaries for both the projects you own and the projects you are a member of. You can configure the frequency of the reports (monthly, on the 1st of every month, or weekly, on Mondays) or turn them off altogether in Account Settings › Email Reports.


c0: attaching_logs
c1: Attaching Logs
c2:
Mychecks ping endpoints accept HTTP HEAD, GET and POST request methods. When using HTTP POST, you can include an arbitrary payload in the request body. Mychecks will log the first 100 kB (100000 bytes) of the request body, so that you can inspect it later. Logging Command Output In this example, we run certbot renew, capture its output (both the stdout and stderr streams), and submit the captured output to Mychecks: We can extend the previous example and signal either success or failure depending on the exit code: If the command produces a lot of output, you may run into the following error: In that case, one workaround is to save the output to a temporary file, then tell curl to send the file as the request body: Using Runitor Runitor is a third-party utility that runs the supplied command, captures its output and reports to Mychecks. It also measures the execution time and retries HTTP requests on transient errors. Best of all, the syntax is simple and clean: Sending Logs Without Signalling Success or Failure You may sometimes want to log diagnostic information without altering the check's current state. Mychecks provides the /log endpoint just for that. When you send an HTTP POST request to this endpoint, Mychecks will log the event and display it in check's "Events" section but will keep the check's state unchanged. Handling More Than 100 kB of Logs While Mychecks can store a small amount of logs in a pinch, it is not specifically designed for that. If you run into the issue of logs getting cut off, consider the following options: See if the logs can be made less verbose. For example, if you have a batch job that outputs a line of text per item processed, perhaps it can output a summary with the totals instead. If the important content is usually at the end, submit the last 100 kB instead of the first. Here is an example that submits the last 100 kB of dmesg output: Finally, if it is critical to capture the entire log output, consider using a dedicated log aggregation service for capturing the logs. Where to See Captured Logs In the check's details page, Events section, click on individual events to see full event details, including the captured log information. In the dialog that opens, use the "Download Original" link to download the request body data, exactly as it was submitted to Mychecks:


c0: bash
c1: Shell Scripts
c2:
You can easily add Mychecks monitoring to a shell script. All you have to do is make an HTTP request at an appropriate place in the script. curl and wget are two common command-line HTTP clients you can use. Here's what each curl parameter does: -m <seconds> Maximum time in seconds that you allow the whole operation to take. --retry <num> If an HTTP request fails, retry up to this many times. By default, curl uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...). See also --retry-delay. -f, --fail Makes curl treat non-200 responses as errors. -s, --silent Silent or quiet mode. Hides the progress meter, but also hides error messages. -S, --show-error Re-enables error messages when -s is used. -o /dev/null Redirect curl's stdout to /dev/null (error messages still go to stderr). Signaling Failure from Shell Scripts You can append /fail or /{exit-status} to any ping URL and use the resulting URL to actively signal a failure. The exit status should be a 0-255 integer. Mychecks will interpret exit status 0 as success and all non-zero values as failures. The following example runs /usr/bin/certbot renew, and uses the $? variable to look up its exit status: Logging Command Output When pinging with HTTP POST, you can put extra diagnostic information in the request body. If the request body looks like a valid UTF-8 string, Mychecks will accept and store the first 100 kB of the request body. In the below example, certbot's output is captured and submitted via HTTP POST: Auto-provisioning New Checks This example uses Mychecks Management API to create a check "on the fly" (if it does not already exist) and retrieve its ping URL. Using this technique, you can write services that automatically register with Mychecks the first time they run.


c0: arduino
c1: Arduino
c2:
The easiest way to send pings from Arduino projects is by using the ArduinoHttpClient library. The below code uses the WiFiNINA network library, and is tested with the Arduino Nano 33 IoT board. The ArduinoHttpClient also works with many other network libraries, including Ethernet and ESP8266WiFi. Note: For simplicity, the network SSID, password and the check's code are hardcoded in this example. In a real-world code, consider storing them in the SECRET_ fields.


c0: php
c1: PHP
c2:
Below is an example of making an HTTP request to Mychecks from PHP. If you would like to setup timeout and retry options, as discussed in the reliability tips section, there is a curl package available that lets you do that easily: Note: this code does not throw any exceptions.


c0: self_hosted
c1: Self-Hosted Healthchecks
c2:
Healthchecks is open-source, and is licensed under the BSD 3-clause license. As an alternative to using the hosted service at https://healthchecks.io, you have the option to host a Healthchecks instance yourself. The building blocks are: Python 3.8+ Django 4 PostgreSQL or MySQL Setting Up for Development You can set up a development environment in a Python virtual environment on your local system to develop a new feature, write a new integration or test a bugfix. The following instructions assume you are using a Debian-based OS. Install dependencies: Prepare directory for project code and virtualenv. Feel free to use a different location: Prepare virtual environment (with virtualenv you get pip, we'll use it soon to install requirements): Check out project code: Install requirements (Django, ...) into virtualenv: Create database tables and a superuser account: With the default configuration, Healthchecks stores data in a SQLite file hc.sqlite in the project directory (~/webapps/healthchecks/). Run tests: Run development server: From another shell, run the sendalerts management command, responsible for sending out notifications: At this point, the site should now be running at http://localhost:8000. Accessing Administration Panel Healthchecks comes with Django's administration panel where you can manually view and modify user accounts, projects, checks, integrations etc. To access it, if you haven't already, create a superuser account: Then, log into the site using the superuser credentials. Once logged in, click on the "Account" dropdown in top navigation, and select "Site Administration". Sending Emails Healthchecks needs SMTP credentials to be able to send emails: login links, monitoring notifications, monthly reports. Specify SMTP credentials using the EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_USE_SSL, and EMAIL_USE_TLS environment variables. Example: You can read more about handling outbound email in the Django documentation, Sending Email section. Receiving Emails Healthchecks comes with a smtpd management command, which starts up an SMTP listener service. With the command running, you can ping your checks by sending email messages. Start the SMTP listener on port 2525: Send a test email: Sending Status Notifications The sendalerts management command continuously polls the database for any checks changing state, and sends out notifications as needed. When sendalerts is not running, the Healthchecks instance will not send out any alerts. Within an activated virtualenv, run the sendalerts command like so: In a production setup, make sure the sendalerts command can survive server restarts. Database Cleanup With time and use, the Healthchecks database will grow in size. You may decide to prune old data: inactive user accounts, old checks not assigned to users, and old records of outgoing email messages. There are separate Django management commands for each task: Remove old records of sent notifications. For each check, remove notifications that are older than the oldest stored ping for the corresponding check. Remove inactive user accounts: Remove old records from the api_tokenbucket table. The TokenBucket model is used for rate-limiting login attempts and similar operations. Any records older than one day can be safely removed. Remove old records from the api_flip table. The Flip objects are used to track status changes of checks, and to calculate downtime statistics month by month. Flip objects from more than 3 months ago are not used and can be safely removed. When you first try these commands on your data, it is a good idea to test them on a copy of your database, and not on the live system. In a production setup, you will want to run these commands regularly, as well as have regular, automatic database backups set up. Next Steps Get the source code. See Configuration for a list of configuration options.


c0: python
c1: Python
c2:
If you are already using the requests library, it is convenient to also use it here: Otherwise, you can use the urllib.request module from Python 3 standard library: You can include additional diagnostic information in the request body (for POST requests):


c0: monitoring_cron_jobs
c1: How to Monitor Cron Jobs with Mychecks
c2:
Mychecks can monitor your cron jobs and notify you when they don't run at expected times. Assuming curl or wget is available, you will not need to install any new software on your servers. The principle of operation is simple: your cron job sends an HTTP request ("ping") to Mychecks every time it completes. When Mychecks does not receive the HTTP request at the expected time, it notifies you. This monitoring technique, sometimes called "heartbeat monitoring", is a type of dead man's switch. It can detect various failure modes: The whole machine goes down (power outage, hardware failure, somebody trips on cables, etc.). The cron daemon is not running or has an invalid configuration. Cron does start your task, but the task exits with a non-zero exit code. The cron job runs for an abnormally long time. Setting Up Let's take a look at an example cron job: To monitor it, first create a new Check in your Mychecks account: After creating the check, copy the generated ping URL , and update the job's definition: The extra curl call lets Mychecks know the cron job has run successfully. Mychecks keeps track of the received pings and notifies you as soon as a ping does not arrive on time. Note: you can alternatively add the extra curl call as a final line inside the /home/me/backup.sh script, to keep the cron job's definition clean and short. You can use an HTTP client other than curl to send the HTTP request. Curl Options The extra options in the above example tell curl to retry failed HTTP requests, limit the maximum execution time, and silence output unless there is an error. Feel free to adjust the curl options to suit your needs. && Run curl only if /home/me/backup.sh exits with an exit code 0. -f, --fail Makes curl treat non-200 responses as errors. -s, --silent Silent or quiet mode. Hides the progress meter, but also hides error messages. -S, --show-error Re-enables error messages when -s is used. -m <seconds> Maximum time in seconds that you allow the whole operation to take. --retry <num> If a transient error is returned when curl tries to perform a transfer, it will retry this number of times before giving up. Setting the number to 0 makes curl do no retries (which is the default). A transient error is a timeout or an HTTP 5xx response code. -o /dev/null Redirect curl's stdout to /dev/null (error messages still go to stderr). Grace Time Grace Time is the amount of extra time to wait when a cron job is running late before declaring it as down. Set Grace Time to be above the expected duration of your cron job. For example, let's say the cron job starts at 14:00 every day and takes between 15 and 25 minutes to complete. The grace time is set to 30 minutes. In this scenario, Mychecks will expect a ping to arrive at 14:00, but will not send any alerts yet. If there is no ping by 14:30, it will declare the job failed and send alerts. Notifications Mychecks has integrations to deliver notifications over different channels: email, webhooks, SMS, chat messages, incident management systems, and more. You can and should set up multiple ways to get notified about job failures: Redundancy: if one notification channel fails (e.g., an email message gets delivered to spam), you will still receive notifications over the other channels. Use different notification methods depending on job priority. You can set up notifications from low-priority jobs to email only, but notifications from high-priority jobs to email, SMS, and team chat. Additionally, to make sure no issues "slip through the cracks", in the Account Settings › Email Reports page you can configure Mychecks to send repeated email notifications every hour or every day as long as any of the jobs is down: Advanced Techniques If your cron job hits an error, you can actively signal it to Mychecks. You can send a "start" signal at the start of the cron job, to track its run time. You can send stdout and stderr output in the HTTP POST body. What about MAILTO? Classic cron implementations have a built-in method of notifying about cron job failures, the MAILTO variable: So why not just use that? There are several drawbacks: For MAILTO to work, the server needs to have a configured MTA. You will not get notified if the whole machine is powered off, or has lost network connection. If your cron job produces any stdout output, you will receive an email every time the job runs. This may result in alert fatigue and you not noticing errors between diagnostic messages. Looking up Your Machine's Time Zone If your cron job consistently pings Mychecks an hour early or an hour late, the likely cause is a timezone mismatch: your machine may be using a timezone different from what you have configured on Mychecks. On modern GNU/Linux systems, you can look up the time zone using the timedatectl status command and looking for "Time zone" in its output: Viewing Cron Logs Using journalctl On a systemd-based system, you can use the journalctl utility to see system logs, including logs from the cron daemon. To see live logs: To see the logs from e.g. the last hour, and only from the cron daemon:


c0: introduction
c1: Mychecks Documentation
c2:
Mychecks is a service for monitoring cron jobs (see guide) and similar periodic processes: Mychecks listens for HTTP requests ("pings") from your cron jobs and scheduled tasks. It keeps silent as long as pings arrive on time. It raises an alert as soon as a ping does not arrive on time. Mychecks works as a dead man's switch for processes that need to run continuously or on a regular, known schedule. Some examples of jobs that would benefit from Mychecks monitoring: filesystem backups, database backups task queues database replication status monitoring scripts report generation scripts periodic data import and sync jobs periodic antivirus scans DDNS updater scripts SSL renewal scripts Mychecks is not the right tool for: monitoring website uptime by probing it with HTTP requests collecting application performance metrics log aggregation Concepts A Check represents a single service you want to monitor. For example, when monitoring cron jobs, you would create a separate check for each cron job to be monitored. Each check has a unique ping URL, a set schedule, and associated integrations. For the available configuration options, see Configuring checks. Each check is always in one of the following states, depicted by a status icon: New. A newly created check that has not received any pings yet. Each new check you create will start in this state. Up. All is well, the last "success" signal has arrived on time. Late. The "success" signal is due but has not arrived yet. It is not yet late by more than the check's configured Grace Time. Down. The "success" signal has not arrived yet, and the Grace Time has elapsed. When a check transitions into the "Down" state, Mychecks sends out alert messages via the configured integrations. Paused. You can manually pause the monitoring of specific checks. For example, if a frequently running cron job has a known problem, and a fix is scheduled but not yet ready, you can pause monitoring of the corresponding check temporarily to avoid unwanted alerts about a known issue. Additionally, if the most recent received signal is a "start" signal, this will be indicated by three animated dots under check's status icon. Ping URL. Each check has a unique Ping URL. Clients (cron jobs, background workers, batch scripts, scheduled tasks, web services) make HTTP requests to the ping URL to signal a start of the execution, a success, or a failure. Mychecks supports two ping URL formats: http://localhost:8000/ping/<uuid> The check is identified by its UUID. Check UUIDs are assigned automatically by Mychecks, and are guaranteed to be unique. http://localhost:8000/ping/<project-ping-key>/<name-slug> The check is identified by project's Ping key and check's slug (user-chosen, URL-friendly identifier). Optionally supports auto-provisioning: if you ping a slug value that does not have a corresponding check, Mychecks can create the check automatically. You can append /start, /fail or /<exitcode> to the base ping URL to send "start" and "failure" signals. The "start" and "failure" signals are optional. You don't have to use them, but you can gain additional monitoring insights if you do use them. See Measuring script run time and Signaling failures for details. You should treat check UUIDs and project Ping keys as secrets. If you make them public, anybody can send telemetry signals to your checks and mess with your monitoring. Read more about Ping URLs in Pinging API. Grace Time is one of the configuration parameters you can set for each check. It is the additional time to wait before sending an alert when a check is late. Use this parameter to account for small, expected deviations in job execution times. If you use "start" signals to measure job execution time, Grace Time also sets the maximum allowed time gap between "start" and "success" signals. If a job sends a "start" signal but then does not send a "success" signal within grace time, Mychecks will assume the job has failed, and send out alerts. An Integration is a specific method for delivering monitoring alerts when a check's change states. Mychecks supports many types of integrations: email, webhooks, SMS, Slack, PagerDuty, etc. You can set up multiple integrations. For each check, you can specify which integrations it should use. For more information on integrations, see Configuring notifications. Project. To keep things organized, you can group checks and integrations in Projects. Your account starts with a single default project, but you can create any number of additional projects as needed. You can transfer existing checks between projects while preserving their configuration and ping URL. Each project has a configurable name, a separate set of API keys, and a separate project team. The project's team is the set of people you have granted read-only or read-write access to the project. For more information on projects, see Projects and teams.


c0: reliability_tips
c1: Pinging Reliability Tips
c2:
Sending monitoring signals over the public internet is inherently unreliable. HTTP requests can sometimes take excessively long or fail completely for a variety of reasons. Here are some general tips to make your monitoring code more robust. Specify HTTP Request Timeout Put a time limit on how long each ping is allowed to take. This is especially important when sending a "start" signal at the start of a job: you don't want a stuck ping to prevent the actual job from running. Another case is a continuously running worker process that pings Mychecks after each completed item. A stuck request could block the whole process. An explicit per-request time limit mitigates this problem. Specifying the timeout depends on the tool you use. curl, for example, has the --max-time (shorthand: -m) parameter: Use Retries To minimize the amount of false alerts you get from Mychecks, instruct your HTTP client to retry failed requests several times. Specifying the retry policy depends on the tool you use. curl, for example, has the --retry parameter: Handle Exceptions Make sure you know how your HTTP client handles failed requests. For example, if you use an HTTP library that raises exceptions, decide if you want to catch the exceptions or let them bubble up.


c0: resources
c1: Third-Party Resources
c2:
A collection of third-party software projects that integrate with Mychecks. Please submit additions and corrections on GitHub. Tools for Self-Hosting linuxserver/docker-healthchecks – Alternative Docker image galexrt/docker-healthchecks – Alternative Docker image iphoting/healthchecks – Deploy Healthchecks to Heroku ansible-collections/community.healthchecksio - Ansible modules for automating tasks on Healthchecks.io Command Runners, Shell Wrappers runitor - A command runner with Healthchecks.io integration to keep your scripts and containers simple. SmartCronHelper – A cron shell wrapper. Automatically registers and pings cron jobs listed in crontab. crontask.sh – Bash wrapper to use in crontab. Supports pinging. task-mon – A small binary for notifying Healthchecks.io when a command runs, written in Rust. API Wrappers Go kristofferahl/go-healthchecksio – Supports listing, creating, updating, deleting, pausing, pinging. frozzare/go-healthchecks – Supports pinging and failing. Javascript pauldenver/healthchecks-io-client – Supports listing, creating, updating, deleting, pausing and pinging checks. Supports listing integrations. jwulf/healthchecks.io – Supports pinging. PHP henrywhitaker3/PHP-healthchecks.io – Supports listing, creating, updating, deleting, pausing, pinging, failing and starting checks. Supports listing integrations. prgTW/healthchecks-bundle – Symfony bundle. Supports listing, creating, pinging, pausing. janiscaunecm/Healthchecks_Magento – Magento module for Healthchecks.io. PowerShell davehope/HealthChecksIOStatusReport – Supports pinging. Python samarpan-rai/healthchecks_wrapper – Python context manager, supports pinging. Ruby gyde-tv/checks – Supports pinging. Rust msfjarvis/healthchecks-rs – Supports all current Ping API and Management API calls. Terraform terraform-provider-healthchecksio – Terraform Provider for Healthchecks.io. Supports creating, updating, deleting checks. Backup Software Integrations binarybucks/restic-tools – Wrapper around restic backup, with Healthchecks.io support. borgmatic – A frontend to Borg, includes Healthchecks.io support. emborg – A frontend to Borg, includes Healthchecks.io support. Dashboards healthchecks/dashboard – A standalone HTML page showing the status of the checks in your account. HealthTray – Watch your healthchecks in Windows system tray. nicoandrade/healthchecks-front – Beautiful & free web dashboard, works great on desktop and mobile.


c0: github_actions
c1: GitHub Actions
c2:
You can augment your GitHub Actions workflows to report success and failure to Mychecks: Note how the jobs Ping-Success and Ping-Failure define Main-Job as their dependency. Ping-Success runs only if Main-Job completes successfully, and Ping-Failure runs when Main-Job fails. To avoid exposing the ping URL, it is a good idea to define it as a secret and access it via the secrets context. Using the workflow_run Trigger Alternatively, you can put the pinging logic in a separate workflow, and configure it to trigger every time your main workflow finishes. The main workflow: And the monitoring workflow:


c0: configuring_notifications
c1: Configuring Notifications
c2:
You can set up multiple ways to receive notifications when checks in your account change state. Doing so is useful for several reasons: Redundancy in case of notification failures. Set up notifications using two different notification channels (for example, email and Slack). If one transport fails (e.g., an email message goes to spam), you still receive a notification over the other channel. Use different notification methods depending on urgency. For example, if a low-priority housekeeping script fails, post a message in chat. If a vital service fails, post in chat, send an email, and send SMS. Route notifications to the right people. Each notification method ("integration") belongs to a project: if you want to use a notification method in multiple projects, you will need to set it up in each project separately. In the web interface, the "Checks" page shows a visual overview of which alerting methods are active for each check. You can click the icons to toggle them on and off: You can also toggle the integrations by clicking the "ON" / "OFF" labels in individual check's details pages: SMS, WhatsApp, and Phone Call Monthly Quotas Mychecks sets a quota on the maximum number of SMS, WhatsApp, and phone-call notifications an account can send per given month. The specific limit depends on the account's billing plan. The quota automatically resets at the start of each month. The "unused" sends from one month do not carry over to the next month. When an account exceeds its monthly limit, Mychecks will: Send a warning email to the account's primary email address Show a warning message on the Integrations page Repeated Notifications If you want to receive repeated notifications for as long as a particular check is down, you have a few different options: If you use an incident management system (PagerDuty, Splunk On-Call, Opsgenie, PagerTree), you can set up escalation rules there. Use the Pushover integration with the "Emergency" priority. Pushover will play a loud notification sound on your phone every 5 minutes until the notification is acknowledged. Mychecks can send hourly or daily email reminders if any check is down in any of your projects. Set them up in Account Settings › Email Reports: Weekly and Monthly Reports Mychecks sends periodic email reports, either monthly at the start of each month, or weekly every Monday. Use them to make sure all checks have their expected state, and nothing has "fallen through the cracks." The reports list checks from all your projects, grouped by project. For each check, they show: check's current status the number of downtimes by month, for the last two months the total downtime duration by month, for the last two months You can opt-out from receiving the reports in the Account Settings › Email Reports page or by clicking the "Unsubscribe" link in the email report's footer.


c0: self_hosted_docker
c1: Running with Docker
c2:
In the Healthchecks source code, /docker/ directory, you can find a sample configuration for running the project with Docker and Docker Compose. Note: For the sake of simplicity, the sample configuration starts a single database node and a single web server node, both on the same host. It does not handle TLS termination. Getting Started Grab the Healthchecks source code from the GitHub repository. Copy docker/.env.example to docker/.env and add your configuration in it. As a minimum, set the following fields: ALLOWED_HOSTS – the domain name of your Healthchecks instance. Example: ALLOWED_HOSTS=hc.example.org. DEFAULT_FROM_EMAIL – the "From:" address for outbound emails. EMAIL_HOST – the SMTP server. EMAIL_HOST_PASSWORD – the SMTP password. EMAIL_HOST_USER – the SMTP username. SECRET_KEY – secures HTTP sessions, set to a random value. SITE_ROOT – The base public URL of your Healthchecks instance. Example: SITE_ROOT=https://hc.example.org. Create and start containers: Create a superuser: Open http://localhost:8000 in your browser and log in with the credentials from the previous step. uWSGI Configuration The reference Dockerfile uses uWSGI as the WSGI server. You can configure uWSGI by setting UWSGI_... environment variables in docker/.env. For example, to disable HTTP request logging, set: Read more about configuring uWSGI in uWSGI documentation. TLS Termination If you plan to expose your Healthchecks instance to the public internet, make sure you put a TLS-terminating reverse proxy in front of it. Important: This Dockerfile uses UWSGI, which relies on the X-Forwarded-Proto header to determine if a request is secure or not. Make sure your TLS-terminating reverse proxy: Discards the X-Forwarded-Proto header sent by the end user. Sets the X-Forwarded-Proto header value to match the protocol of the original request ("http" or "https"). For example, in NGINX you can use the $scheme variable like so: Pre-built Images Pre-built Docker images, built from the Dockerfile in the /docker/ directory, are available on Docker Hub. The images are built automatically for every new release. The Docker images support amd64, arm/v7 and arm64 architectures. To use a pre-built image for Healthchecks version X.Y, in the docker-compose.yml file replace the "build" section with:


c0: configuring_checks
c1: Configuring Checks
c2:
In Mychecks, a Check represents a single service you want to monitor. For example, when monitoring cron jobs, you would create a separate check for each cron job to be monitored. Mychecks pricing plans are structured primarily around how many checks you can have in your account. You can create checks either in Mychecks web interface or via Management API. Name, Tags, Description Describe each check using an optional name, slug, tags, and description fields. Name: names are optional, but it is a good idea to set them. Good naming becomes especially important as you add more checks to the account. Mychecks will display check names in the web interface, in email reports, and in notifications. Slug: URL-friendly identifier, used in slug-based ping URLs (an alternative to the default UUID-based ping URLs). The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. If you don't plan to use slug-based ping URLs, you can leave the slug field empty. Tags: a space-separated list of optional labels. Use tags to organize and group checks within a project. You can tag checks by the environment (prod, staging, dev, etc.) or by role (www, db, worker, etc.) or using any other system. Description: a free-form text field with any related information for your team or your future self. Describe the cron job's role, who set it up, what to do in case of failures, where to look for additional information. Simple Schedules Mychecks supports two types of schedules: Simple and Cron. Use Simple schedules for monitoring processes that you expect to run at relatively regular time intervals: once an hour, once a day, once a week. For the simple schedules, you can configure two parameters, Period and Grace Time. Period is the expected time between pings. Grace Time is the additional time to wait before sending an alert when a check is late. Use this parameter to account for small, expected deviations in job execution times. Note: if you use the "start" signal to measure job run times, then Grace Time also specifies the maximum allowed time gap between "start" and "success" signals. Whenever Mychecks receives a "start" signal, it expects to receive a subsequent "success" signal within Grace Time. If the success signal does not arrive within the configured Grace Time, Mychecks will mark the check as failed and send out alerts. Cron Schedules Use "cron" for monitoring processes with more complex schedules. This monitoring mode ensures that jobs run at the correct time, and not just at the correct time intervals. You will need to specify Cron Expression, Server's Time Zone, and Grace Time. Cron Expression is the cron expression you specified in the crontab. Server's Time Zone is the timezone of your server. The cron daemon typically uses the system's local time. If the machine is not using the UTC timezone, you need to specify it here. Grace Time, same as for simple schedules, is how long to wait before sending an alert for a late check. Filtering Rules In the "Filtering Rules" dialog, you can control several advanced aspects of how Mychecks handles incoming pings for a particular check. Allowed request methods for HTTP requests. You can require the ping requests to use HTTP POST. Use the "Only POST" option if you run into issues of preview bots hitting the ping URLs when you send them in email or post them in chat. Filter by keywords in the Subject line. When pinging via email, look for specific keywords in the subject line. If the subject line contains any of the keywords listed in Start Keywords, Success Keywords, or Failure Keywords, Mychecks will assume it to be a start, a success, or a failure signal respectively. This is useful if, for example, your backup software sends an email after each backup run with a different subject line depending on success or failure. Filter by keywords in the message body. Same as the previous option, but looks for the keywords in the email message body. Supports both plain text and HTML email messages. Pinging a Paused Check. Normally, when you ping a paused check, it leaves the paused state and goes into the "up" state (or the "down" state in case of a failure signal). You can change this behavior by selecting the "Ignore the ping, stay in the paused state" option. With this option selected, the paused state becomes "sticky": Mychecks will ignore all incoming pings until you explicitly resume the check.


c0: powershell
c1: PowerShell
c2:
You can use PowerShell and Windows Task Scheduler to automate various tasks on a Windows system. From within a PowerShell script, it is also easy to ping Mychecks. Here is a simple PowerShell script that pings Mychecks. When scheduled to run with Task Scheduler, it will send regular "I'm alive" messages. Of course, you can extend it to do more things. You can send additional diagnostic information in HTTP POST requests: For other parameters, you can use in the Invoke-RestMethod cmdlet, see the official Invoke-RestMethod documentation. As an alternative to putting the script in a .ps1 file, you can also pass it to PowerShell directly, using the "-Command" argument:


