Adding Custom Check Adapters

Relevant source files

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

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

Introduction

Custom Check Adapters in StatusBeam are specialized modules within the Domain Layer (packages/core) designed to probe external services and translate their native health indicators into the standardized StatusBeam CheckStatus. This system allows the project to move beyond simple HTTP pings by mirroring the status of third-party platforms like Atlassian Statuspage, incident.io, and Sentry.

The architecture is built on a framework-free foundation, ensuring that adapters only depend on pure logic and basic libraries like zod. Adapters are primarily invoked by the Check Layer during scheduled cron runs or via inbound webhooks to update the system state in real-time.

Sources: ARCHITECTURE.md:12-32, README.md:113-134

Core Adapter Architecture

The check pipeline centers on the checkSite function, which acts as a dispatcher for different check types. It utilizes injectable dependencies, such as fetchImpl and now, to maintain testability and platform independence.

The Dispatcher Logic

The checkSite function evaluates the site.check configuration property to determine which adapter to execute.

The diagram shows how checkSite routes requests to specific adapter functions based on configuration.
Sources: packages/core/src/check.ts:36-54

Data Structures

Adapters must return a CheckResult object. Significant fields include:

Field	Type	Description
slug	string	Unique identifier for the service.
status	CheckStatus	The resolved status (up, degraded, or down).
code	number	The HTTP status code (or 0 for network failures).
responseTime	number	Time taken for the probe in milliseconds.
checkedAt	string	ISO timestamp of the check execution.
error	string (optional)	Error message if the check failed.

Sources: packages/core/src/check.ts:63-95

Implementing a Polling Adapter

Polling adapters, such as the Statuspage and incident.io implementations, fetch data from an external API and map the response to internal statuses.

Status Mapping

Adapters typically define a mapping table to convert external strings to StatusBeam types.

External Status	CheckStatus
operational / none	up
degraded_performance / minor / maintenance	degraded
partial_outage	degraded
major_outage / major / critical	down

Sources: packages/core/src/check.ts:97-120

Validation and Error Handling

Adapters use zod schemas to validate the shape of external payloads at the boundary. This ensures that malformed JSON or proxy error pages are reported as down with a validation error rather than causing a runtime crash.

export const statuspageSummarySchema = z.object({
  status: z.object({
    indicator: z.string().optional(),
  }).optional(),
  components: z.array(z.object({
    id: z.string().optional(),
    name: z.string().optional(),
    status: z.string().optional(),
  })).optional(),
})

Sources: packages/core/src/check.ts:127-145, packages/core/src/check.test.ts:153-170

Implementing a Webhook Adapter

Webhook adapters allow services like Sentry and Statuspage to push updates directly to the StatusBeam Worker. This provides real-time status updates between scheduled cron ticks.

Webhook Flow

When a webhook hits the /webhooks/:provider/:slug endpoint, the system validates the payload and updates the KV snapshot.

The diagram illustrates the ingestion flow for real-time status updates via webhooks.
Sources: apps/worker/src/webhook.handler.test.ts:133-149, ARCHITECTURE.md:46-52

Payload Parsing

Webhook adapters must handle various event types. For example, the Sentry adapter distinguishes between created issues (monitor failing) and resolved issues (monitor recovered).
Sources: packages/core/src/sentry-webhook.test.ts:5-15, packages/core/src/statuspage-webhook.test.ts:17-30

Summary of Adapter Requirements

To add a new custom adapter, the following components must be implemented in packages/core:

1. Configuration Schema Extension: Update siteSchema to accept the new check type.
2. Mapping Logic: Define the translation between the external service's status indicators and CheckStatus.
3. Boundary Validation: Define a zod schema for the external API response or webhook payload.
4. Dispatcher Integration: Add the logic to checkSite (for polling) or the webhook handler (for real-time updates).
5. Unit Tests: Co-locate tests to verify status derivation and error handling.

Sources: packages/core/src/check.ts:36-54, ARCHITECTURE.md:120-125, README.md:154-175