jackson2w/claude-code-skills / cloudflare-cron-telegram-alert
cloudflare-cron-telegram-alert
VerifiedThis 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |