Check Providers & Adapters

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/check.ts
• packages/core/src/statuspage-webhook.ts
• packages/core/src/sentry.test.ts
• packages/core/src/check.test.ts
• ARCHITECTURE.md
• README.md
• apps/worker/src/sentry-webhook.handler.test.ts

Check Providers & Adapters constitute the core ingest engine of StatusBeam. This system is responsible for probing external services, mirroring third-party status pages, and ingesting real-time webhooks to determine the health of monitored components. By decoupling the check logic into specific adapters, StatusBeam can support diverse monitoring methods ranging from simple HTTP pings to complex vendor-specific API integrations.

The architecture is designed to run primarily within a Cloudflare Cron Worker, which executes scheduled probes and writes the resulting state to D1 and KV stores. This ensures that the status page remains independent of the infrastructure being monitored.

Sources: ARCHITECTURE.md:12-25, README.md:112-140

Core Check Architecture

The system utilizes a unified interface for executing checks, primarily through the checkSite function. This function dispatches logic based on the check type defined in the user's configuration.

Check Dispatch Logic

The following diagram illustrates how a scheduled check is routed to the appropriate adapter:

The checkSite function is the primary entry point for all monitoring activities. It accepts a Site configuration and optional dependencies like a custom fetch implementation.

Sources: packages/core/src/check.ts:44-57, ARCHITECTURE.md:79-88

Check Status Derivation

For standard HTTP checks, status is derived from both the HTTP status code and the measured response time.

Status	Condition
up	HTTP code is in expectedStatusCodes AND responseTime <= maxResponseTime.
degraded	HTTP code is in expectedStatusCodes AND responseTime > maxResponseTime.
down	HTTP code is NOT in expectedStatusCodes OR a network/parsing error occurred.

Sources: packages/core/src/check.ts:15-28, packages/core/src/check.test.ts:32-44

External Adapters

Statuspage & incident.io

StatusBeam provides an adapter to mirror Atlassian Statuspage and incident.io pages. It works by fetching the vendor's /api/v2/summary.json endpoint and mapping their indicator or specific component status to StatusBeam's internal status types.

• URL Resolution: Bare page URLs are automatically transformed to point to the summary API (e.g., https://status.claude.com becomes https://status.claude.com/api/v2/summary.json).
• Targeting: Users can monitor an entire page's overall indicator or target a specific component by ID or case-insensitive name.

Sources: packages/core/src/check.ts:133-146, packages/core/src/check.ts:161-175, README.md:214-222

Status Mapping Table

Vendor Status	StatusBeam Status
operational / none	up
minor / degraded_performance / partial_outage	degraded
major / critical	down
maintenance / under_maintenance	degraded

Sources: packages/core/src/check.ts:101-118, packages/core/src/check.test.ts:98-112

Sentry Uptime

The Sentry adapter mirrors Sentry Uptime monitors by querying the Sentry Issues API. It searches for unresolved issues that match the configured monitor.

• Poll Backstop: The adapter builds a query (defaulting to is:unresolved level:error) against the Sentry organization's issues endpoint.
• Authentication: Requires a SENTRY_AUTH_TOKEN passed as a Bearer header.

Sources: packages/core/src/sentry.test.ts:25-37, packages/core/src/sentry.test.ts:88-100, README.md:224-228

Webhook Ingest Pipeline

In addition to scheduled polling, StatusBeam supports real-time status updates via inbound webhooks for Statuspage and Sentry. This allows for near-instant status updates without waiting for the next cron cycle.

Webhook Flow

Webhook handlers validate the payload shape at the boundary using Zod schemas before processing.

Sources: ARCHITECTURE.md:38-44, apps/worker/src/sentry-webhook.handler.test.ts:98-118

Provider-Specific Webhook Logic

• Statuspage: Handles both component_update events and incident events where affected components carry status updates.
• Sentry: Maps created actions (unresolved issues) to down and resolved actions to up. It also supports triggered actions for metric alerts.

Sources: packages/core/src/statuspage-webhook.ts, packages/core/src/sentry-webhook.test.ts:49-65

Data Structures

The system relies on specific data structures to maintain consistency between the check engine and the display layer.

Structure	Purpose	Derived From
CheckResult	The output of a single check run.	checkSite execution
StatuspageSummary	The validated shape of an external Statuspage API response.	summary.json
SentryWebhook	The validated shape of an inbound Sentry issue alert.	Webhook POST body

Sources: packages/core/src/check.ts:121-131, packages/core/src/check.ts:60-75

Summary of Logic

The Check Providers and Adapters system provides a resilient monitoring framework by combining active polling with passive webhook ingestion. By using Cloudflare's edge primitives, it ensures that even if the primary fetch fails (resulting in a status code of 0), the system accurately reports a "down" state while preserving the context of the failure in the error field of the CheckResult. This multi-layered approach allows StatusBeam to provide reliable uptime data regardless of the target service's stability.

Sources: ARCHITECTURE.md:144-153, packages/core/src/check.ts:77-100