Skip to content

jackson2w/claude-code-skills / cloudflare-cron-telegram-alert

cloudflare-cron-telegram-alert

Verified

This skill should be used when scaffolding a Cloudflare Worker that runs on a cron trigger, checks something external (a URL, an API, a heartbeat), and sends a Telegram alert only on failure — e.g. an uptime monitor, a health check, a dead-man's-switch. Trigger phrases include "cron trigger uptime monitor", "Telegram alert Worker", "cloudflare cron health check", "scheduled Worker Telegram", "uptime monitor Cloudflare Worker", "dead man's switch worker".

Cloudflare Cron + Telegram Alert Worker

A minimal, reusable shape for "check something on a schedule, alert only when it's broken" — built out fully for a tailnet uptime monitor; the same shape fits any periodic external check.

Project shape

wrangler.jsonc      # cron trigger, no public route (see below)
src/index.ts        # scheduled() handler + fetch() stub
package.json
tsconfig.json
.gitignore          # node_modules/, .wrangler/, .dev.vars, worker-configuration.d.ts

wrangler.jsonc essentials:

{
  "name": "<worker-name>",
  "main": "src/index.ts",
  "compatibility_date": "<recent date>",
  "observability": { "enabled": true },
  "workers_dev": false,      // no public HTTP route needed — cron-only
  "preview_urls": false,
  "triggers": { "crons": ["*/5 * * * *"] }
}

Disable workers_dev/preview_urls explicitly. A cron-only Worker gets a public *.workers.dev route by default on first deploy unless these are set — unnecessary attack surface for something that never needs inbound HTTP.

Handler pattern

export interface Env {
  TELEGRAM_BOT_TOKEN: string;
  TELEGRAM_CHAT_ID: string;
  TARGET_URL: string;
}

export default {
  async scheduled(_event, env, ctx): Promise<void> {
    ctx.waitUntil(checkTarget(env));
  },
  async fetch(): Promise<Response> {
    return new Response("cron-only Worker; use wrangler dev --test-scheduled to test");
  },
} satisfies ExportedHandler<Env>;

async function checkTarget(env: Env): Promise<void> {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 10_000);
  try {
    const res = await fetch(env.TARGET_URL, { signal: controller.signal });
    if (!res.ok) await sendTelegramAlert(env, `Check FAILED: ${res.status} ${res.statusText}`);
  } catch (err) {
    await sendTelegramAlert(env, `Check FAILED: ${err instanceof Error ? err.message : err}`);
  } finally {
    clearTimeout(timeout);
  }
}

async function sendTelegramAlert(env: Env, text: string): Promise<void> {
  const res = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: env.TELEGRAM_CHAT_ID, text }),
  });
  if (!res.ok) console.error(`Telegram alert delivery failed: ${res.status} ${await res.text()}`);
}

Alert only on failure — never on success. No "still up" ping every cron cycle. This matches the minimal-noise-notification standard already used for Grafana alerting in this homelab; a Worker that pings Telegram every 5 minutes even when healthy trains the recipient to ignore the channel.

Secrets, not vars

All three values (bot token, chat ID, target URL) go in as wrangler secret put <NAME> — interactive prompt or piped via printf '%s' "$VALUE" | wrangler secret put NAME, never as a CLI argument or vars in the committed config, even for values that aren't strictly sensitive (the target URL, for instance) — keeps the pattern uniform and avoids the actual secrets (bot token) accidentally sitting next to a hardcoded non-secret in the same config block.

Testing before deploy

# .dev.vars (gitignored) with the same keys as a fake/test target
npx wrangler dev --test-scheduled --port 8788 &
curl http://localhost:8788/__scheduled

Test both paths before deploying: point TARGET_URL at something healthy (expect silence, no Telegram call) and at something unreachable (expect a logged Telegram delivery attempt, even if the bot token is a placeholder and the call itself 404s — that still proves the failure branch fires correctly).

Verifying in production

wrangler tail shows real cron invocations ("*/5 * * * *" @ <time> - Ok), but macOS has no timeout binary by default — don't chain timeout N wrangler tail; run it via nohup ... & and kill it manually, or use the harness's own backgrounding (run_in_background: true on the Bash tool) instead of trying to bound it client-side.

The big gotcha: what can this Worker actually reach?

If the check target lives on a private network (a Tailscale Serve URL, an internal VPN address, a LAN-only host), a Cloudflare Worker cannot reach it — Workers run on Cloudflare's public edge, not inside any private network. A Tailscale Serve hostname resolves via real public DNS (needed for the HTTPS cert) to the node's private tailnet IP (CGNAT 100.64.0.0/10), which is only routable from inside that tailnet — the Worker's fetch() will fail every single cron cycle, indistinguishable from "the service is actually down." Before wiring the target URL, confirm the check target is genuinely reachable from the public internet — a Tailscale Funnel endpoint (not Serve), a real public IP, or an intentionally-exposed health path. See the proxmox-terraform-provisioning skill / this project's Tailscale gotchas for the pattern of narrowing a Funnel'd endpoint to a single secret-gated health path rather than exposing a whole app just to make it checkable from outside.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall