What this skill does

# Webhook Router for OpenClaw A general-purpose webhook receiver that routes incoming webhooks from any source to appropriate handlers. Integrates seamlessly with OpenClaw's hooks system and Tailscale Funnel for secure, public webhook endpoints. ## Overview This skill provides a complete webhook routing infrastructure: - **Secure endpoint** via Tailscale Funnel (HTTPS) - **Automatic routing** based on webhook source - **Built-in handlers** for GitHub, ClawHub, and generic sources - **Registration system** for adding new webhook sources - **Audit logging** of all received webhooks - **Smart alerting** on important events ## How It Works ### Architecture ``` External Service → Tailscale Funnel → OpenClaw /hooks → router.sh → Handler Script ``` 1. External service sends webhook to your Tailscale Funnel URL 2. OpenClaw's hooks system receives the webhook 3. `router.sh` inspects the payload and routes to the appropriate handler 4. Handler processes the event and triggers alerts/actions as needed ### Your Webhook Endpoint ``` https://gregs-mac-mini.taila31444.ts.net/hooks ``` **Authentication:** Use OpenClaw's hook token in the `X-Hook-Token` header: ``` X-Hook-Token: 19e78f0288d476ee1197d4b374b6f73394abe121c12cc38a ``` ## Quick Start ### 1. Verify Tailscale Funnel is Running ```bash openclaw gateway status # Should show: Tailscale Funnel: ACTIVE ``` If not active: ```bash openclaw gateway start ``` ### 2. Test the Router Locally ```bash cd /Users/gregborden/.openclaw/workspace/clawhub-skills/webhook-router ./test.sh ``` ### 3. Register a New Webhook Source ```bash ./register.sh github my-repo # Output: https://gregs-mac-mini.taila31444.ts.net/hooks?source=github-my-repo ``` ### 4. Configure in Your Service Use the generated URL in your service's webhook settings with the hook token header. ## Available Handlers ### GitHub (`handlers/github.sh`) Handles GitHub webhook events: - **push** - Code pushed to repository - **pull_request** - PR opened, closed, merged, synchronized - **issues** - Issue opened, closed, assigned, labeled - **release** - Release published **Alert triggers:** - PR merged → Notification - Issue assigned to you → Notification - New release → Notification **Configuration:** ```bash # Set your GitHub username for personalized alerts export GITHUB_USERNAME="your-username" ``` ### Generic (`handlers/generic.sh`) Fallback handler for unknown webhook sources: - Logs full payload - Attempts to extract event type and meaningful fields - Creates alert for manual review ### ClawHub (`handlers/clawhub.sh`) Handles ClawHub-specific webhooks (auto-created by `register.sh`): - New skill published - Skill updated - User mentions ## Registration System ### Register a New Source ```bash ./register.sh <source-type> <name> ``` **Examples:** ```bash # GitHub repository ./register.sh github my-awesome-app # Stripe payments ./register.sh stripe payments # Custom service ./register.sh custom my-service ``` This will: 1. Generate a unique source identifier 2. Create a handler template (if new source type) 3. Output the webhook URL to configure ### Webhook URL Format ``` https://gregs-mac-mini.taila31444.ts.net/hooks?source=<source-id> ``` Or with header: ``` X-Webhook-Source: <source-id> ``` ## Advanced Configuration ### Custom Handler Development Create a new handler in `handlers/<type>.sh`: ```bash #!/bin/bash # handlers/myapp.sh PAYLOAD="$1" SOURCE="$2" EVENT_TYPE="$3" # Extract fields using jq field=$(echo "$PAYLOAD" | jq -r '.field // "unknown"') # Log to vault vault write "webhooks/$SOURCE/$EVENT_TYPE" \ --data "$PAYLOAD" \ --tags "webhook,$SOURCE,$EVENT_TYPE" # Alert on important events if [[ "$EVENT_TYPE" == "critical" ]]; then alert "🚨 Critical event from $SOURCE" "$field" fi ``` Make it executable: ```bash chmod +x handlers/myapp.sh ``` ### Environment Variables ```bash # GitHub username for personalized alerts export GITHUB_USERNAME="your-github-username" # Alert channel (default: main) export WEBHOOK_ALERT_CHANNEL="telegram" # Log file path (default: /Users/gregborden/.openclaw/workspace/memory/webhooks.jsonl) export WEBHOOK_LOG_PATH="/custom/path/webhooks.jsonl" ``` ### Log Format All webhooks are logged to `/Users/gregborden/.openclaw/workspace/memory/webhooks.jsonl`: ```json { "timestamp": "2026-02-07T20:30:00Z", "source": "github-myrepo", "event_type": "push", "repository": "owner/repo", "sender": "username", "payload_hash": "sha256:abc123...", "processed": true } ``` ## Service-Specific Setup ### GitHub 1. Go to repository → Settings → Webhooks → Add webhook 2. **Payload URL:** `https://gregs-mac-mini.taila31444.ts.net/hooks?source=github-<repo>` 3. **Content type:** `application/json` 4. **Secret:** (leave blank, token is in header) 5. **Events:** Select events or "Let me select individual events" 6. Add header: `X-Hook-Token: 19e78f0288d476ee1197d4b374b6f73394abe121c12cc38a` ### Stripe 1. Dashboard → Developers → Webhooks → Add endpoint 2. **Endpoint URL:** `https://gregs-mac-mini.taila31444.ts.net/hooks?source=stripe-payments` 3. Select events to listen for 4. Add header: `X-Hook-Token: 19e78f0288d476ee1197d4b374b6f73394abe121c12cc38a` ### ClawHub Use the built-in hooks integration or register: ```bash ./register.sh clawhub skills ``` ### Custom Services Any service that supports webhooks: 1. Run `./register.sh <type> <name>` 2. Copy the generated URL 3. Configure in your service with the `X-Hook-Token` header ## Testing ### Local Test ```bash ./test.sh ``` Sends mock webhooks to test the routing system. ### Manual Test with curl ```bash # GitHub push event curl -X POST "https://gregs-mac-mini.taila31444.ts.net/hooks?source=github-test" \ -H "X-Hook-Token: 19e78f0288d476ee1197d4b374b6f73394abe121c12cc38a" \ -H "X-GitHub-Event: push" \ -H "Content-Type: application/json" \ -d '{ "ref": "refs/heads/main", "repository": {"full_name": "test/repo"}, "pusher": {"name": "testuser"}, "commits": [{"message": "Test commit"}] }' ``` ## Troubleshooting ### Check Recent Webhooks ```bash # View last 10 webhooks tail -10 /Users/gregborden/.openclaw/workspace/memory/webhooks.jsonl | jq . ``` ### Verify Handler Exists ```bash ls -la handlers/ ``` ### Test Router Directly ```bash echo '{"test": "data"}' | ./router.sh --source test --event push ``` ### Check OpenClaw Hooks Status ```bash openclaw gateway status ``` ### Logs - Webhook audit log: `/Users/gregborden/.openclaw/workspace/memory/webhooks.jsonl` - Handler logs: Check your vault or notification channel ## Security Notes - The hook token authenticates requests to OpenClaw - Tailscale Funnel provides HTTPS encryption - Webhook payloads are logged (hashed) but consider sanitizing sensitive data - Each source can have its own validation in its handler ## Files - `router.sh` - Main routing logic - `register.sh` - Source registration - `handlers/github.sh` - GitHub webhook handler - `handlers/generic.sh` - Generic fallback handler - `test.sh` - Test suite - `SKILL.md` - This documentation ## License MIT - See ClawHub repository for details.