Queue-Based Notification Engine

Relevant source files

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

• apps/worker/src/index.ts
• packages/core/src/notify.ts
• ARCHITECTURE.md
• README.md
• status.config.example.yml
• packages/core/CHANGELOG.md

The Queue-Based Notification Engine is a decoupled system within StatusBeam responsible for delivering alerts when service statuses change. It acts as the "Notify Layer," separating the time-critical service probing logic from the potentially slow or unreliable process of communicating with external third-party APIs like Slack or generic webhooks.

By utilizing a queue-based architecture, the engine ensures that notification failures—such as network timeouts or rate limits from external providers—do not block or crash the primary cron worker responsible for service checks. This system supports both an "inline" delivery mode for immediate, best-effort POST requests and a "queue" mode that leverages Cloudflare Queues for automatic retries and dead-lettering.

Sources: README.md, ARCHITECTURE.md

Architecture and Data Flow

The notification engine is triggered when the check Worker detects a difference between the current service status and the previous snapshot stored in KV. The process flows from detection to payload construction, and finally to delivery via the configured channel.

Notification Workflow

1. Status Change Detection: The check Worker compares the new check results with the previous summary snapshot in KV.
2. Payload Generation: If changes are detected, the system builds a channel-agnostic StatusChangePayload containing details about the affected sites.
3. Dispatching: Depending on the configuration, the payload is either sent directly via HTTP (inline) or pushed to a Cloudflare Queue.

The following diagram illustrates the lifecycle of a notification event from detection to external delivery:

Delivery Modes

StatusBeam supports two primary delivery strategies configured via the notifications.delivery field in the system configuration.

Mode	Description	Reliability	Requirements
inline	Default mode. The Worker performs fetch requests directly to targets using ctx.waitUntil.	Best-effort; no retries on failure.	None (standard Workers).
queue	Enqueues events to Cloudflare Queues for processing by a consumer.	High; supports automatic retries and dead-lettering.	Cloudflare Queues binding.

Sources: status.config.example.yml, README.md

Inline Dispatch Logic

In inline mode, dispatchNotifications is called within ctx.waitUntil. It maps through the configured notification targets (Slack webhooks and generic webhooks) and executes them using Promise.allSettled. This ensures that one failing target (e.g., a deleted Slack webhook) does not prevent other notifications from being sent.

Sources: ARCHITECTURE.md, apps/worker/src/index.ts

Queue-Based Dispatch Logic

When configured for queue delivery, the notification event is enqueued. This offloads the execution to a separate worker instance, providing a buffer against external API downtime. Cloudflare Queues provide a 24-hour dead-letter retention on the Free plan and up to 14 days on the Paid plan.

Sources: README.md, packages/core/CHANGELOG.md

Configuration and Payloads

Notifications are configured in the status.config.yml file. This includes the delivery mode and the specific channel settings.

Configuration Schema

notifications:
  delivery: inline # inline | queue
  slack:
    webhookUrl: https://hooks.slack.com/services/...
  webhooks:
    - url: https://example.com/status-hook

Sources: status.config.example.yml

Data Structures

The engine utilizes specific TypeScript interfaces defined in the core package to ensure consistency across the worker and the notification logic.

• StatusChangePayload: Contains the statusPageName, statusPageUrl, and an array of changes (each containing the site name, slug, previous status, and new status).
• SlackMessage: A structured object formatted for the Slack Incoming Webhooks API, generated by toSlackMessage.

Sources: packages/core/src/notify.ts

Security and Error Handling

• URL Redaction: To prevent sensitive information from leaking into logs, URLs are often redacted to their origin before logging in the worker.
• Non-Blocking Execution: Notification failures are logged but never thrown. This prevents a bad notification target from wedging a cron run.
• Secret Management: Sensitive values like webhookUrl or CF_API_TOKEN (used for cache purging linked to status changes) are stored as Cloudflare Worker secrets rather than in the public YAML configuration.

Sources: ARCHITECTURE.md, status.config.example.yml, apps/worker/src/index.ts

Conclusion

The Queue-Based Notification Engine provides a robust mechanism for alerting users of service disruptions. By separating notification delivery from service monitoring and offering a Queue-backed reliable path, StatusBeam ensures that status updates are delivered consistently without impacting the performance of the core monitoring pipeline.