Mattering Automations Healthchecks.io integration
Connect Healthchecks.io to Mattering Automations: create, update, pause, resume and delete checks, read their status, ping history, diagnostics and status changes, and send the pings themselves by UUID or by slug. One credential covers both the management API and the separate pinging host.
The Mattering Automations Healthchecks.io integration puts cron and background-job monitoring on your automation canvas. Twenty three nodes, eight that read and fifteen that act, spanning both halves of the product: the Management API v3, where checks are created, updated, paused, resumed and deleted and where status, ping history, diagnostic bodies, status changes, notification integrations and public badges are read, and the separate pinging host, where the actual signals arrive as success, start, failure, an exit status or a plain log entry.
One connector covers both hosts because the workflows worth building cross the boundary: run Healthchecks: List Checks with the management key, branch on what you find, then ping the check you found, all on one connection to one project. The two hosts are genuinely different, though. The management API sends JSON and authenticates with an X-Api-Key header. The pinging host sends plain text, has no header authentication at all, and on its UUID-addressed endpoints answers HTTP 200 even when it recorded nothing, with a not-found body that starts with the letters OK. That is the failure mode this integration exists to handle, and it is covered in detail below.
The highest-value thing to point this at is Mattering itself. Ending a scheduled workflow with Healthchecks: Ping Success gives you dead man's switch monitoring: Healthchecks.io raises the alarm the day that ping stops arriving, which is the one failure no error handler inside the workflow can catch, because a run that never starts reports nothing. The rest of this page is the setup walkthrough, the node reference, how the three key grades differ, and the failures worth recognising on sight.
Before you start
- A Healthchecks.io account and at least one project in it. API keys are project-specific and there are no account-wide keys, so one credential in Mattering is one Healthchecks.io project. Monitoring two projects means connecting this integration twice.
- A read-write API key for that project, created on its Project Settings page. This is the key to fill in first: it is the only grade that reaches all thirteen management endpoints and the only one that returns check UUIDs, which the pickers in this integration need.
- Optionally, the project's ping key, if you want the slug-addressed ping nodes. It lives on the same settings page. The UUID-addressed ping nodes need no credential at all, because a check's UUID is itself the secret that authorises a ping against it.
- An awareness that a check UUID is a credential. Anyone holding one can report success or failure on that job's behalf, so treat a UUID as you would a key: keep it out of shared documents, logs and chat transcripts.
- Enough room in your plan. The free Hobbyist tier allows twenty monitored jobs and keeps a hundred log entries per job. The check limit is per ACCOUNT and shared across every project the account owns, so a second project does not come with a second allowance. Creating a check past the limit is refused rather than silently ignored.
- This integration connects to the HOSTED Healthchecks.io service at healthchecks.io and hc-ping.com. Healthchecks is open source and can be self-hosted, but a self-hosted instance is not something these nodes can be pointed at.
- A Mattering workspace with access to the Automations app.
Collect the project's keys
A Healthchecks.io project can carry three separate secrets, and they are different things rather than three spellings of one. The read-write API key goes in an [[X-Api-Key]] header and reaches every management endpoint. The read-only API key goes in the same header but reaches only four endpoints and censors what it returns. The ping key is not a header at all: Healthchecks.io puts it into the URL path of the slug-addressed ping endpoints. All three fields on the Mattering credential are optional, because the useful subsets are real, and the connect test below reports which of them it actually found.
Connect Healthchecks.io to Mattering
Verify it works
Open any automation canvas and check the palette: a Healthchecks.io section should list eight read nodes and fifteen action nodes. Drop Healthchecks: List Checks onto the canvas and run a test step. It takes no parameters, has no pagination to walk and returns the whole project in one response, which makes it the natural probe: each check comes back with its name, its current status, its schedule, when it last pinged and when the next ping is due, plus the UUID and slug every other node uses.
Look at whether the UUIDs are actually there. If Healthchecks: List Checks returns checks with no uuid and no ping_url but with a unique_key instead, the connection resolved a READ-ONLY key. That is not a fault, but it limits the integration to four endpoints and no UUID-addressed pings, so fill in the read-write key if that was not what you intended.
Open the Check picker on a node such as Healthchecks: Ping Success and confirm it lists your checks by name with their current status underneath. The status line is there on purpose: a paused check and a healthy one look identical by name, and reporting a job's health against a check nobody is watching is a silent failure.
Run Healthchecks: Get Service Status once. It takes no credential at all and answers with a short OK when Healthchecks.io's own database is reachable. It is worth knowing about before an incident, because it is what separates Healthchecks.io being down from your key being wrong. Everything in this verify path is read-only and cannot send a ping, so it raises no alerts and is safe to re-run whenever you want to check the connection.
Node reference
23 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 8
Healthchecks: Get Check
healthchecks_get_check
Read one check by its UUID or by the unique_key a read-only API key returns instead. Use it to poll a single job's status without pulling the whole project, or to confirm a change landed after an update. This is one of only two endpoints that accept either identifier, which makes it the read-only path into a single check.
Healthchecks: Get Ping Body
healthchecks_get_ping_body
Fetch the diagnostic text a job sent with one specific ping, which is where a failing cron job's log output or stack trace ends up. The response is plain text and is returned verbatim under a body field rather than parsed as JSON. A ping with no stored body answers HTTP 404, the same code as a missing check or a missing ping number, so an absent body is not distinguishable from a bad reference here.
Healthchecks: Get Service Status
healthchecks_get_service_status
Ask Healthchecks.io whether its own database is reachable. Answers HTTP 200 with the body OK when healthy and HTTP 500 when not. This is the one endpoint on the whole API that needs no credential, which makes it the honest way to tell Healthchecks.io being down apart from your key being wrong before an automation escalates. The response is plain text, not JSON, and is returned under a body field.
Healthchecks: List Badges
healthchecks_list_badges
Get the public badge URLs for every tag in the project, plus a special asterisk entry covering the project as a whole. Each tag comes with six URLs: svg, json and shields for a two-state badge that treats a check in its grace period as still up, and svg3, json3 and shields3 for a three-state badge that reports up, late and down separately. Use these to publish live status into a README, a status page or a dashboard. The URLs are unguessable but unauthenticated, so anyone holding one can read that tag's status. Works with a read-only API key.
Healthchecks: List Checks
healthchecks_list_checks
List every check in the project, with its current status, its schedule, when it last pinged and when the next ping is due. This is the starting point for most Healthchecks automations: run it on a schedule and branch on any check whose status is down, or use it to find the UUID a ping node needs. There is no pagination on this endpoint and none is possible, so the response holds the whole project every time. Works with a read-only API key, which censors the response: uuid, ping_url, update_url, pause_url, resume_url and channels are removed and a stable unique_key is added in their place.
Healthchecks: List Integrations
healthchecks_list_integrations
List the project's notification integrations with their UUIDs, names and kinds, such as email, sms, slack or webhook. Its main use is feeding the channels field on Healthchecks: Create Check and Healthchecks: Update Check, which wants integration UUIDs or exact names. Also worth running on its own as an audit: an integration nobody remembers configuring is where alerts go to be ignored. Needs a read-write API key; a read-only key cannot reach this endpoint at all.
Healthchecks: List Pings
healthchecks_list_pings
Read a check's recent ping history, most recent first: what kind of event each ping was, when it arrived, which IP and user agent sent it, its run ID, and how long the run took when a start ping was matched to a finishing one. Use it to chart run durations or to find out what actually happened before a check went down. The number of pings returned is capped by the plan and cannot be paged past: 100 on free accounts and 1000 on paid ones. Older pings are simply not reachable through the API.
Healthchecks: List Status Changes
healthchecks_list_flips
List the moments a check changed state, up to down or down to up, as a plain time series. This is the endpoint behind uptime reporting and incident timelines: each row is a timestamp and an up value of 1 or 0. Filter it to a trailing number of seconds, or to a start and end range. Retention is the current month plus the two months before it, so a window reaching further back returns nothing rather than failing, and an empty result means either a check that never flipped or a window that is too old. Works with a read-only API key, and accepts the unique_key such a key returns in place of the UUID.
Action nodes 15
Healthchecks: Create Check
healthchecks_create_check
Create a check, which is the object a job pings to prove it ran. Give it a timeout for a simple period check, or a cron or systemd OnCalendar expression for a scheduled one; the schedule wins if you send both. This endpoint is also an upsert: fill in the match-on fields and an existing check is updated instead of a second one being created. The status code says which happened, 201 for a new check and 200 for an updated one, and this node surfaces that as a created flag rather than hiding it. On the free plan the 21st check is refused with HTTP 403 and the message that the account has hit its check limit, which the vendor documents as twenty checks per free account.
Healthchecks: Delete Check
healthchecks_delete_check
Permanently delete a check along with its ping history and its status history. There is no trash and no undo. The UUID dies with it and cannot be reissued, so every ping URL baked into a server for this check stops working, and those servers are told nothing: their pings will keep returning HTTP 200 with a not-found body. The deleted check is returned in the response, which is the only record of it you will get.
Healthchecks: Pause Check
healthchecks_pause_check
Stop monitoring a check without deleting it, so a planned maintenance window or a decommissioned job does not raise alerts. Put this at the start of a deployment automation and Healthchecks: Resume Check at the end. A paused check normally wakes up on its next ping; a check created with manual resume on stays paused until it is resumed explicitly.
Healthchecks: Ping Exit Status
healthchecks_ping_exit_status
Report a process exit status and let Healthchecks.io decide what it means: 0 is success, anything from 1 to 255 is a failure. This is the node to use when an upstream step gives you a numeric result and you would otherwise have to branch to pick between the success and failure nodes. A value above 255 is refused by Healthchecks.io with HTTP 400 and the body invalid exit status. Marked destructive for endpoint testing because a non-zero value alerts every integration on the check.
Healthchecks: Ping Exit Status by Slug
healthchecks_ping_exit_status_by_slug
Report a process exit status against a check identified by slug and project ping key. Zero records a success and anything from 1 to 255 records a failure and alerts, so a numeric result from an upstream step can be forwarded without branching. Values above 255 are refused with HTTP 400. Marked destructive for endpoint testing because a non-zero value alerts every integration on the check.
Healthchecks: Ping Failure
healthchecks_ping_fail
Report a failure immediately instead of waiting for the check's period and grace to lapse. Put this on the error branch of an automation and an alert goes out in seconds rather than hours, with whatever you put in the ping body attached as the diagnostic. This node sends real alerts to every integration assigned to the check, which is why it is marked destructive for endpoint testing even though it changes no configuration. Reports failure honestly rather than trusting the HTTP 200 this endpoint returns even when nothing was recorded.
Healthchecks: Ping Failure by Slug
healthchecks_ping_fail_by_slug
Report a failure immediately, addressing the check by slug and project ping key. Put it on an automation's error branch with the error message in the ping body so the alert carries the diagnosis with it. This sends real alerts to every integration assigned to the check, which is why it is marked destructive for endpoint testing. Uses real HTTP status codes: 404 for an unmatched slug, 409 for an ambiguous one, 429 when rate limited.
Healthchecks: Ping Log
healthchecks_ping_log
Attach a note to a check's event log without changing its status. Use it to record progress through a long job, or to leave a breadcrumb explaining what a run was doing, so that when the check does go down the timeline says why. The check's state and its next-ping deadline are untouched. Reports failure honestly: the vendor's documentation says this endpoint answers 404 for an unknown check, and the live service answers HTTP 200 with a not-found body instead, so this node checks the body either way.
Healthchecks: Ping Log by Slug
healthchecks_ping_log_by_slug
Add a note to a check's event log without changing its status, addressing the check by slug and project ping key. Useful for recording progress through a long job so the timeline explains itself if the check later goes down. The check's state and its next-ping deadline are untouched.
Healthchecks: Ping Start
healthchecks_ping_start
Tell Healthchecks.io a job has just started. Optional, but it buys two things nothing else can: measured run durations, and an alert when a job runs LONGER than its grace period rather than only when it fails to finish. Pair it with a success or failure ping at the end and send the same run ID on both so overlapping runs are matched correctly. A start ping with no matching finish leaves the run open. Reports failure honestly rather than trusting the HTTP 200 this endpoint returns even when nothing was recorded.
Healthchecks: Ping Start by Slug
healthchecks_ping_start_by_slug
Signal that a job has started, addressing the check by slug and project ping key rather than by UUID. Gives you measured durations and an alert when a run overruns its grace period. Send the same run ID on the start and the finish so concurrent runs of the same job are paired correctly. Uses real HTTP status codes: 404 for an unmatched slug, 409 for an ambiguous one, 429 when rate limited.
Healthchecks: Ping Success
healthchecks_ping_success
Tell Healthchecks.io that a job finished successfully. Put this at the end of any Mattering automation that has to run on schedule and Healthchecks.io will raise an alert the day it stops arriving, which is the whole point of dead man's switch monitoring: it catches the automation that silently stopped running, which no error handler can. You can attach diagnostic text as the ping body. This node reports failure honestly: Healthchecks.io answers HTTP 200 even when the UUID matches no check and even when the ping was rate limited, so the node reads the response body and only reports success when the check genuinely recorded the ping.
Healthchecks: Ping Success by Slug
healthchecks_ping_success_by_slug
Report a job's success by its human-readable slug instead of its UUID, using the project's ping key. This is the form to reach for when the automation knows the job by name, when checks are created and destroyed by infrastructure so no UUID can be baked in, or when a job should be able to register itself the first time it runs. Unlike the UUID form, this endpoint uses real HTTP status codes: 404 when the slug matches nothing, 409 when it matches more than one check, 429 when rate limited, and 201 when auto-provisioning created the check.
Healthchecks: Resume Check
healthchecks_resume_check
Put a paused check back into monitoring. Its status returns to new, meaning it is watched again but has not been pinged since resuming. Resuming a check that is not paused is refused with HTTP 409 and the message that the check is currently not in a paused state, so this is safe to run without checking first.
Healthchecks: Update Check
healthchecks_update_check
Change an existing check: rename it, retag it, widen its grace period, swap a timeout for a cron schedule, or reassign which integrations it alerts. Only the fields you fill in are sent, so everything left blank keeps its current value. Note the verb: Healthchecks.io updates with POST, not PUT or PATCH, and a PUT to this URL is refused with HTTP 405.
Using the integration
The HTTP 200 that means nothing was recorded
This is the most important thing to understand about the pinging half, and it is why these nodes exist rather than a bare HTTP call. On the UUID-addressed ping endpoints Healthchecks.io returns HTTP 200 whether or not it recorded anything. That is deliberate on the vendor's side: those URLs go into crontabs, and a non-2xx would make a shell script treat a monitoring hiccup as a failed job. The vendor documents two such cases, a ping for a check it cannot find and a ping dropped for exceeding the rate limit, and both answer 200 with a short explanation in the body. The sting is that the not-found body BEGINS with the letters OK, so a status-code test passes and a careful body-prefix test also passes. Every ping node here compares the body exactly and returns three things a workflow can branch on: a boolean saying whether the ping was recorded, a named outcome such as recorded, created, not found, rate limited or ambiguous slug, and the verbatim body so an unrecognised answer is visible rather than swallowed. Anything unrecognised fails CLOSED, because a monitoring integration that reports green when it does not understand the answer is worse than one that reports red.
UUID pings and slug pings, and when to use which
Ten ping nodes cover five signals in two addressing forms. Use the UUID form, such as Healthchecks: Ping Success, when the workflow knows the specific check and the UUID can be stored on it. Use the slug form, such as Healthchecks: Ping Success by Slug, when the workflow knows the job by name, when checks are created and destroyed alongside the infrastructure they watch so no UUID can be baked in, or when a job should be able to register itself the first time it runs. The two behave differently under failure and it is worth knowing which you are on: the UUID form answers 200 to everything, while the slug form uses real HTTP status codes, with a not found for an unmatched slug, a conflict for a slug that matches more than one check, and a real rate-limit code. The slug form needs the project's ping key; the UUID form needs no credential at all.
Monitoring your own Mattering automations
The failure this catches is the one nothing inside a workflow can report: the scheduled run that never happened. End a scheduled automation with Healthchecks: Ping Success and Healthchecks.io alerts you the day that ping stops arriving, whether the workflow errored, was disabled, or quietly stopped being scheduled. Put Healthchecks: Ping Failure on the error branch with the error text as the ping body and the alert goes out in seconds rather than after the check's period and grace lapse, carrying the diagnosis with it. Add Healthchecks: Ping Start at the top of the run and you also get measured durations and an alert when a run overruns its grace period, which is how a job that has hung rather than failed gets noticed. Send the same run ID on the start and the finish so that overlapping runs are paired correctly, and use Healthchecks: Ping Log between phases to leave breadcrumbs that explain the timeline afterwards.
Creating checks from a workflow, and the upsert
Healthchecks: Create Check takes either a timeout for a simple period check or a cron or systemd OnCalendar expression for a scheduled one, and the schedule wins if you send both. It is also an upsert: list the fields to match on and an existing check is updated instead of a duplicate being created, which is what makes it safe to run from a provisioning workflow that might execute twice. The status code says which happened, and the node surfaces it, so a run that returns an existing check rather than a new one is visible rather than confusing. Healthchecks: Update Check changes an existing one and sends only the fields you fill in, so anything left blank keeps its current value. Note the verb if you are comparing with a hand-rolled call: Healthchecks.io updates with POST, and a PUT to that URL is refused.
Pausing around planned work
Healthchecks: Pause Check stops monitoring without deleting anything, so a deployment or a migration does not page whoever is on call. Put it at the start of the automation and Healthchecks: Resume Check at the end. Resume is safe to call unconditionally: resuming a check that is not paused is refused with a clear conflict rather than doing something unexpected, so the end of a workflow does not have to remember what the start of it did. A paused check normally wakes on its next ping, unless it was created with manual resume turned on, in which case it stays paused until it is resumed explicitly.
Reading history when something did break
Three read nodes reconstruct an incident. Healthchecks: List Status Changes gives the moments a check flipped between up and down as a plain time series of a timestamp and an up value, which is the raw material for a timeline or an uptime report. Filter it to a trailing number of seconds or to a start and end range. Healthchecks: List Pings gives the recent ping history, most recent first, with the kind of each event, when it arrived, the sending address and user agent, the run ID and the measured duration where a start ping was matched to a finish. Healthchecks: Get Ping Body then fetches the diagnostic text a specific ping carried, which is where a failing job's log output or stack trace ends up. Two retention facts shape what you will find: status changes are kept for the current month plus the two months before it, and ping history is capped as a COUNT per plan rather than a period, at a hundred entries per job on the free tier and a thousand on the paid ones, with no way to page past the cap to anything older.
Notification routing and the channels field
Healthchecks: List Integrations lists the project's notification integrations with their identifiers, names and kinds, and it is worth running on its own as an audit, because an integration nobody remembers configuring is where alerts go to be ignored. Its other job is feeding the Channels field on Healthchecks: Create Check and Healthchecks: Update Check, which takes a comma-separated list of integration identifiers or exact names, plus a wildcard meaning all of them. That field stays free text rather than a picker precisely because it is a list with a wildcard, and a single-value picker would foreclose both. Healthchecks: List Badges is the publishing counterpart: it returns the public badge URLs for every tag in the project plus one covering the project as a whole, in two-state and three-state variants, so a workflow can push live job status into a README or an internal page without anyone copying URLs by hand.
The one delete, and why it is worse than most
Healthchecks: Delete Check removes a check along with its ping history and its status history, with no trash and no undo. The part that catches people is the UUID: it dies with the check and cannot be reissued, so every ping URL baked into a server or a crontab for that check stops working, and those servers are told nothing at all. Their pings keep returning HTTP 200 with a not-found body, which is the same silent-green failure described above, now permanent. The node returns the deleted check in its response, which is the only record of it that survives. Where the intent is temporary, Healthchecks: Pause Check is almost always the node that was actually wanted.
On the automation canvas
Drag a Healthchecks.io node onto a canvas, attach the credential once, and wire it to schedules, conditions, AI steps and every other connector in the workspace. This integration ships no trigger nodes, because the vendor's API is something you call rather than something that calls you, so the pattern for reacting to a check going down is polling: Healthchecks: List Checks returns the whole project in one call with no pagination, which makes a schedule that runs every few minutes and branches on any down check a complete solution for most teams. If you want push instead, Healthchecks.io's own notification integrations include a webhook kind, which can be pointed at a webhook trigger on a Mattering automation. That is configured on the Healthchecks.io side rather than through these nodes.
From AI assistants over MCP
These nodes are also exposed over MCP, an open protocol for connecting AI assistants to tools, so Claude, ChatGPT and any other MCP-capable assistant can work with Healthchecks.io through your Mattering workspace, with Matter, the assistant built into the platform, using the same nodes natively. A useful boundary: the eight read nodes plus pause and resume are easy to hand over, while Healthchecks: Delete Check destroys a UUID that cannot be reissued and the four failure-reporting ping nodes send real alerts to real people, so those belong behind a condition or a human approval.
Troubleshooting
A ping node reports failure even though the response was HTTP 200
Test Connection returns 401, and the message says a key is missing even though one was sent
Checks come back without a uuid or a ping_url, and the check pickers are empty
A node refuses with a message about the key grade rather than returning data
A slug-addressed ping returns not found, or a conflict about an ambiguous slug
Creating a check is refused with a forbidden response
Creating a check returned an existing check instead of a new one
Resuming a check is refused with a conflict
Status changes come back empty for a period you know had an outage
Ping history stops short of the run you are looking for
A workflow reports success but the check still went down
A management API call returns a rate-limit error
Related
The Healthchecks.io MCP
What connecting Healthchecks.io unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Healthchecks.io is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.