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#

text

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#

text

https://gregs-mac-mini.taila31444.ts.net/hooks

Authentication: Use OpenClaw's hook token in the X-Hook-Token header:

text

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#

text

https://gregs-mac-mini.taila31444.ts.net/hooks?source=<source-id>

Or with header:

text

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.