Real-Time Webhook Ingestion

Relevant source files

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

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

Real-Time Webhook Ingestion is a mechanism within StatusBeam that allows external service providers to push status updates directly to the platform. While the primary data source is a periodic Cloudflare Cron Trigger, webhooks provide a "push" model to ensure the status page reflects incidents the moment they are reported by upstream providers such as Atlassian Statuspage, Sentry, or incident.io.

This system is implemented as a fetch() handler within the Cloudflare Worker (apps/worker/src/index.ts). It listens for inbound POST requests, validates the payload against specific provider schemas, and feeds the resulting status changes into the same ingest pipeline used by the cron-based probes. This ensures consistent data storage in D1 and summary snapshots in KV.

Sources: ARCHITECTURE.md:27-30, README.md:154-159

System Architecture and Data Flow

The webhook ingestion flow begins when an external provider sends a POST request to a specific endpoint. The worker validates the request using a shared secret, parses the provider-specific payload, maps it to a StatusBeam status, and updates the internal state.

Webhook Ingestion Flow

The following diagram illustrates the sequence of events from an external trigger to a status page update.

Supported Providers and Endpoint Mapping

StatusBeam provides dedicated handlers for different status providers. Each webhook URL includes a :provider type and a :slug that identifies which site in the status.config.yml should be updated.

Provider	Endpoint Pattern	Description
Statuspage	/webhooks/statuspage/:slug	Ingests Atlassian Statuspage component or page updates.
incident.io	/webhooks/statuspage/:slug	Uses Statuspage-compatible payloads for incident.io pages.
Sentry	/webhooks/sentry/:slug	Ingests Sentry Uptime monitor issue alerts.

Sources: README.md:225-240, apps/worker/src/webhook.handler.test.ts:114-125

Authentication and Security

Webhook endpoints are secured using a WEBHOOK_SECRET environment variable. Inbound requests must provide this secret as a token query parameter. If the secret is unset or the provided token is incorrect, the handler "fails closed" and returns a 401 Unauthorized response.

// Example of a request requiring authentication
// Sources: apps/worker/src/webhook.handler.test.ts:98-100
it('401s on a wrong token', async () => {
  const { env, ctx } = makeEnv('s3cret')
  const res = await handleWebhook(post('/webhooks/statuspage/claude-api?token=WRONG', majorOutage), env, ctx)
  expect(res.status).toBe(401)
})

Sources: apps/worker/src/webhook.handler.test.ts:88-105, apps/worker/src/sentry-webhook.handler.test.ts:75-80

Ingestion Logic

Payload Validation

StatusBeam uses Zod schemas to validate inbound JSON bodies at the boundary. If the payload does not match the expected structure for the specified provider, the handler returns a 400 Bad Request.

Sources: ARCHITECTURE.md:124-126, packages/core/src/statuspage-webhook.test.ts:37-43

Status Mapping

Each provider's specific terminology is mapped to a unified StatusBeam state (e.g., up, degraded, down).

• Statuspage/incident.io Mapping: Maps status_indicator (none, minor, major, critical) or component statuses (operational, degraded_performance, partial_outage, major_outage) to internal states.
• Sentry Mapping: Maps Sentry issue actions (created, resolved, triggered) to binary up/down states. An unresolved issue maps to down, while a resolved issue maps to up.

Sources: packages/core/src/statuspage-webhook.test.ts:57-65, packages/core/src/sentry-webhook.test.ts:40-52

Site Filtering

Webhooks often send updates for multiple components. The ingestion engine filters events to only process those matching the specific slug or component ID configured in status.config.yml. Events for unrelated components return a 204 No Content and are ignored to prevent unnecessary database writes.

Sources: apps/worker/src/webhook.handler.test.ts:127-135, packages/core/src/statuspage-webhook.test.ts:98-105

Integration with Storage and Cache

When a valid webhook event is processed:

1. D1 Storage: A new row is inserted into the checks table containing the mapped status and response code.
2. KV Update: The summary key in KV is rewritten to include the updated status for the affected site.
3. Cache Invalidation: If a status change is detected, the Worker issues a purge request to the Cloudflare Workers Cache using Cache-Tags. This ensures that the edge-cached status page and API responses are updated near-instantly.

Sources: ARCHITECTURE.md:83-88, apps/worker/src/webhook.handler.test.ts:137-148, README.md:278-285

Summary

Real-Time Webhook Ingestion enables StatusBeam to maintain high accuracy by reducing the latency between an upstream failure and its reflection on the status page. By leveraging the same ingest pipeline as the cron-based system, it ensures that all status updates—whether pushed or pulled—are subject to the same notification and caching logic, providing a resilient and consistent experience for end users.