Overwatch is built around a small set of concepts that compose into a complete monitoring setup. Understanding how monitors, check results, statuses, alert channels, and organizations relate to each other will help you configure Overwatch effectively and interpret what you see in the dashboard and API responses. This page covers each concept in depth.
Monitors
A monitor is a recurring check that Overwatch runs against a target on a defined interval. Every monitor has a type, a configuration, and a current status. Monitors belong to an organization, and you can attach one or more alert channels to each monitor so that the right people are notified when its status changes.
Monitor types
Overwatch supports five monitor types:
| Type | What it checks |
|---|
| HTTP | Sends an HTTP request to a URL and evaluates the response status code and latency. |
| TCP | Opens a TCP connection to a host and port to verify the service is reachable. |
| TLS | Connects to a domain and inspects the SSL/TLS certificate — validity, expiration date, and presence. |
| DNS | Queries a DNS record and compares the result against a known-good baseline. |
| SCHEDULED | Heartbeat monitoring — your job pings a unique check-in URL; Overwatch alerts if it stops hearing from the job on schedule. |
Monitor configuration
Each monitor type accepts a config object with type-specific fields. Common fields include:
url (HTTP) — the endpoint to request.host / port (TCP) — the hostname and port to connect to.interval — how often to run the check, in seconds. The minimum value depends on your plan.alertChannelIds — optional list of alert channel IDs to attach at creation time.
For SCHEDULED monitors, Overwatch sets the internal interval automatically and returns a checkinUrl in the creation response. Your job must call that URL to signal successful completion.
Check results
Each time a monitor runs, Overwatch records a check result. A check result captures:
- Status — the outcome of this specific run (see status values below).
- Latency — for HTTP and TCP checks, the round-trip time in milliseconds.
- Detail — additional structured data depending on the check type (e.g., HTTP status code, certificate expiry date, DNS record value).
- Alert outcome — whether an alert fired and how it was delivered.
Overwatch retains check results for 90 days on Starter and Pro plans, and up to 2 years on Enterprise.
Statuses
Every monitor has a current status that reflects the outcome of its most recent check. Status values differ by monitor type.
HTTP and TCP
| Status | Meaning |
|---|
up | The check succeeded and latency is within normal range. |
degraded | The check succeeded but latency is significantly higher than the 30-day moving average. |
down | The check failed — the endpoint did not respond or returned an unexpected status. |
TLS
| Status | Meaning |
|---|
active | The certificate is valid and not close to expiration. |
expiring_soon | The certificate is valid but will expire within the configured warning threshold. |
expired | The certificate has passed its expiration date. |
no_cert | No certificate was found at the target domain. |
DNS
| Status | Meaning |
|---|
present | The DNS record exists and matches the expected value. |
missing | The DNS record does not exist. |
changed | The DNS record exists but differs from the known-good baseline. |
Scheduled (heartbeat)
| Status | Meaning |
|---|
ok | The job checked in within the expected interval and grace window. |
failed | The job checked in but reported a failure. |
havent_heard | The job has not checked in within the expected interval plus the grace window. |
Organization-level status
Overwatch also computes an overall status for your entire organization, visible on the dashboard and in the /api/v1/status endpoint:
| Overall status | Condition |
|---|
operational | All monitors are in a healthy state. |
degraded | At least one monitor is in a warning state (degraded, expiring_soon, havent_heard, or changed). No monitors are down. |
incident | At least one monitor is in a failing state (down, expired, missing, or failed). |
Alert channels
An alert channel is a delivery destination for notifications. Overwatch fires an alert on a monitor when that monitor’s status changes — for example, when an HTTP endpoint transitions from up to down, or when a certificate moves from active to expiring_soon. Alerts also fire on recovery.
Supported channel types
- Slack — posts a formatted message to a Slack channel via the Overwatch Slack app.
- Discord — delivers a notification to a Discord server channel via webhook.
- Microsoft Teams — sends a message card to a Teams channel via webhook.
- Email — sends a notification to one or more email addresses.
- Webhook — sends a JSON POST to any URL, making it compatible with PagerDuty, custom scripts, and other tools.
PagerDuty and SMS are defined in the data model but are not yet available through the API or dashboard. Use a webhook to route alerts to PagerDuty in the meantime.
Organizations
All resources in Overwatch — monitors, alert channels, API keys, and team members — belong to an organization. When you sign up, Overwatch creates an organization for you automatically.
Multiple organizations
You can be a member of more than one organization. Use the organization switcher in the dashboard to move between them. Each organization has its own monitors, billing subscription, and member list.
Roles
Every organization membership has a role that controls what actions the member can perform:
| Role | Permissions |
|---|
owner | Full access, including billing and organization deletion. |
admin | Can create, edit, and delete monitors and alert channels. Can invite and remove members. Cannot manage billing. |
viewer | Read-only access to monitors, check results, and alert channels. Cannot make changes. |
viewer role can only read data; a key with the admin or owner role can create and modify resources.
API keys
An API key is a long-lived credential that authenticates requests to the Overwatch REST API on behalf of an organization. Keys are scoped to an organization and carry a role, just like a human member.
All API keys start with the prefix ow_live_sk_. You pass the key in the Authorization header of every API request:
Authorization: Bearer ow_live_sk_<your-key>
Generating a key
Generate API keys in Settings → Security. The full key value is shown only once at creation — copy it immediately and store it securely. Overwatch stores only a hash of the key and cannot display it again.
Keys can be given an expiration date. Overwatch rejects requests from expired keys with a 401 Unauthorized response.
Treat API keys like passwords. Do not commit them to version control or share them in public channels. If a key is compromised, delete it from Settings → Security and generate a new one.
