mirror of
https://github.com/tiennm99/claude-status-webhook.git
synced 2026-04-17 15:20:37 +00:00
tiennm99
976a2594b7
- Hash inputs in timingSafeEqual to prevent length leak side-channel - Add quote escaping to escapeHtml for defense in depth - Normalize chatId to Number in parseKvKey for type consistency - Log Retry-After header on 429 rate limit responses - Slim README to focused overview, move details to docs/ - Add docs/: system-architecture, setup-guide, feature-decisions - Add documentation section and README guidelines to CLAUDE.md
118 lines
3.0 KiB
Markdown
118 lines
3.0 KiB
Markdown
# Setup Guide
|
|
|
|
## Prerequisites
|
|
|
|
- [Node.js](https://nodejs.org/) (v18+)
|
|
- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (free tier is sufficient)
|
|
- A [Telegram bot token](https://core.telegram.org/bots#how-do-i-create-a-bot) from [@BotFather](https://t.me/BotFather)
|
|
|
|
## Tech Stack
|
|
|
|
| Component | Technology |
|
|
|-----------|-----------|
|
|
| Runtime | [Cloudflare Workers](https://workers.cloudflare.com/) |
|
|
| Storage | [Cloudflare KV](https://developers.cloudflare.com/kv/) |
|
|
| Queue | [Cloudflare Queues](https://developers.cloudflare.com/queues/) |
|
|
| HTTP framework | [Hono](https://hono.dev/) |
|
|
| Telegram framework | [grammY](https://grammy.dev/) |
|
|
|
|
## Deployment
|
|
|
|
### 1. Clone and install
|
|
|
|
```bash
|
|
git clone https://github.com/tiennm99/claude-status-webhook.git
|
|
cd claude-status-webhook
|
|
npm install
|
|
```
|
|
|
|
### 2. Authenticate with Cloudflare
|
|
|
|
```bash
|
|
npx wrangler login
|
|
```
|
|
|
|
### 3. Create KV namespace and Queue
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```jsonc
|
|
"kv_namespaces": [
|
|
{ "binding": "claude_status", "id": "YOUR_KV_NAMESPACE_ID" }
|
|
]
|
|
```
|
|
|
|
### 4. Set secrets
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
Run the setup script to register bot commands and set the Telegram webhook:
|
|
|
|
```bash
|
|
node scripts/setup-bot.js
|
|
```
|
|
|
|
It will prompt for your bot token and worker URL. You should see `{"ok":true}` for both webhook and commands.
|
|
|
|
### 7. Configure Statuspage webhook
|
|
|
|
1. Go to [status.claude.com](https://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
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
This starts a local dev server with wrangler that emulates KV and Queues locally. Test with curl:
|
|
|
|
```bash
|
|
# 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" }
|
|
}'
|
|
```
|