claude-status-webhook/README.md

claude-status-webhook

Telegram bot that forwards Claude Status updates to subscribed users. Whenever an incident or component status change occurs on Claude's status page, subscribers receive a Telegram notification instantly.

Hosted on Cloudflare Workers with KV for storage and Queues for reliable message fan-out. Fully serverless, fully free tier.

Features

• Incident notifications — new incidents, updates, and resolutions with impact severity
• Component status changes — e.g., API goes from Operational → Degraded Performance
• Per-user subscription preferences — subscribe to incidents only, components only, or both
• Supergroup topic support — send /start in a specific topic and notifications go to that topic
• On-demand status check — /status fetches live data from status.claude.com
• Self-healing — automatically removes subscribers who block the bot

Bot Commands

Command	Description
/start	Subscribe to notifications (default: incidents + components)
/stop	Unsubscribe from notifications
/status	Show current status of all components
/status <name>	Show status of a specific component (fuzzy match)
/subscribe incident	Receive incident notifications only
/subscribe component	Receive component update notifications only
/subscribe all	Receive both (default)

Prerequisites

• Node.js (v18+)
• A Cloudflare account (free tier is sufficient)
• A Telegram bot token from @BotFather

Setup

1. Clone and install

git clone https://github.com/tiennm99/claude-status-webhook.git
cd claude-status-webhook
npm install

2. Authenticate with Cloudflare

npx wrangler login

3. Create KV namespace and Queue

npx wrangler kv namespace create claude-status
npx wrangler queues create claude-status

Copy the KV namespace ID from the output and update wrangler.jsonc:

"kv_namespaces": [
  { "binding": "claude_status", "id": "YOUR_KV_NAMESPACE_ID" }
]

4. Set secrets

npx wrangler secret put BOT_TOKEN
# Paste your Telegram bot token

npx wrangler secret put WEBHOOK_SECRET
# Choose a random secret string for the Statuspage webhook URL

5. Deploy

npm run deploy

Note the worker URL from the output (e.g., https://claude-status-webhook.<your-subdomain>.workers.dev).

6. Set up Telegram bot

Visit the setup URL in your browser to register bot commands and set the Telegram webhook in one step:

https://<WORKER_URL>/webhook/setup/<WEBHOOK_SECRET>

You should see a JSON response with {"ok":true} for both webhook and commands.

7. Configure Statuspage webhook

1. Go to status.claude.com
2. Click Subscribe to Updates → Webhook
3. Enter the webhook URL: <WORKER_URL>/webhook/status/<WEBHOOK_SECRET>

Replace <WEBHOOK_SECRET> with the secret you set in step 4.

Local Development

npm run dev

This starts a local dev server with wrangler that emulates KV and Queues locally. You can test the Statuspage webhook with curl:

# Test incident webhook
curl -X POST http://localhost:8787/webhook/status/your-test-secret \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "event_type": "incident.created" },
    "incident": {
      "name": "API Degraded Performance",
      "status": "investigating",
      "impact": "major",
      "shortlink": "https://stspg.io/xxx",
      "incident_updates": [{ "body": "We are investigating the issue.", "status": "investigating" }]
    }
  }'

# Test component webhook
curl -X POST http://localhost:8787/webhook/status/your-test-secret \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "event_type": "component.updated" },
    "component": { "name": "API", "status": "degraded_performance" },
    "component_update": { "old_status": "operational", "new_status": "degraded_performance" }
  }'

Tech Stack

• Runtime: Cloudflare Workers
• Storage: Cloudflare KV
• Queue: Cloudflare Queues
• HTTP framework: Hono
• Telegram framework: grammY

License

Apache-2.0