Health Checks#

A platform connection can look configured and still be broken: an expired access token, a webhook the platform silently dropped, an exhausted quota. Health checks make actual API calls against the platform to prove a connection works, and return structured per-test results.

Health checks are per platform connection and are available on platforms that declare the health_check capability. Running one on a platform without the capability returns a BAD_REQUEST error.

Running a Health Check#

Open a platform connection in the console and run a check to execute the full suite for that connection. The result looks like:

{
  "valid": true,
  "message": "All tests passed",
  "tests": [
    {
      "name": "Authentication",
      "status": "pass",
      "message": "Authenticated as My Bot",
      "details": { "bot_id": "12345", "bot_username": "my_bot" }
    },
    {
      "name": "Webhook Configuration",
      "status": "pass",
      "message": "Webhook is configured",
      "details": { "configured": true, "url": "https://api.outeract.com/webhooks/..." }
    }
  ],
  "data": {}
}

valid is true only when every test passed.
message is the overall summary.
tests holds the individual results (see below).
data carries platform-specific metadata (account info, token expiry, quotas).

Health checks operate on platform connection credentials, so they run in the [console](https://outeract.com/console) rather than through the API-key developer API. For programmatic, API-key-based monitoring see [Health Monitoring](/docs/guides/health-monitoring/).

What Gets Checked#

Each platform implements its own suite, but checks fall into common categories:

Test	What it verifies
Authentication	Credentials work; the check makes a real API call (e.g. fetch bot/account info), not merely a format check
Webhook Configuration	The webhook is registered with the platform and points at the right URL; surfaces pending update counts and the platform’s last delivery error where available
API Quota	Rate limits / quota headroom on the platform side
Platform-specific	E.g. phone number verification status on WhatsApp

For webhook-capable platforms, the check reads live webhook status from the platform’s API (configured, current url, pending_update_count, and any last_error), so a webhook the platform has disabled shows up even though your Outeract config looks fine.

Interpreting Statuses#

Each test reports one of four statuses:

Status	Meaning	Effect on `valid`
`pass`	Test succeeded	n/a
`warning`	Works, but needs attention (e.g. webhook not yet configured, token nearing expiry)	Connection can still be `valid`
`fail`	Test failed; the connection is not fully functional	Forces `valid: false`
`info`	Informational only	n/a

flowchart LR
    HC["Health check"] --> T{"Any test<br/>failed?"}
    T -->|yes| F["valid: false<br/>fix credentials / config"]
    T -->|no| W{"Any<br/>warnings?"}
    W -->|yes| WB["valid, with warnings<br/>review test details"]
    W -->|no| OK["Healthy"]

Typical responses to each state:

fail on Authentication: credentials are wrong, revoked, or expired. Update the connection config (or re-run OAuth for OAuth platforms).
fail/warning on Webhook Configuration: re-register the webhook. On platforms with webhook auto-setup, the console’s Reconnect Webhook button re-registers the URL with the platform.
warning elsewhere: read details; these usually predict a future failure (quota pressure, upcoming expiry).

Console vs API#

The console (https://outeract.com/console) surfaces health continuously:

Each connection shows a health badge (healthy, warning with a tooltip listing the warning tests, or failing) with results cached briefly and optionally polled.
The connection detail view lists every test with its status, message, and details, plus a manual re-check button.
Reconnect Webhook is available directly from the connection when the webhook test degrades, re-registering the webhook URL with the platform.

Testing Credentials Before Saving#

The connection setup flow validates a configuration without creating or modifying a connection: it builds a temporary connection in a transaction, runs the health check against it, and rolls everything back. Use the Test connection step to catch bad credentials before they ever go live.

An extended mode additionally sends test messages to any configured health-check numbers or handles; the default only validates credentials.