ngrok-unofficial-webhook-skill – OpenClaw Skill

---

name: ngrok-unofficial-webhook-skill description: Start an ngrok tunnel to receive incoming webhooks and process them via the LLM. Use when the user asks to listen for webhooks, set up a webhook endpoint, start ngrok, or when another skill (like Zoom RTMS Meeting Assistant) needs a public webhook URL. Receives webhook payloads and lets the LLM decide how to handle them.

Ngrok Webhook Listener

Start a public webhook endpoint via ngrok. Incoming webhooks are auto-routed to matching skills or presented to the user for manual handling.

Prerequisites

cd skills/ngrok-unofficial-webhook-skill
npm install

Environment Variables

Set in the skill's .env file (copy from .env.example).

Required:

• NGROK_AUTHTOKEN — ngrok auth token from https://dashboard.ngrok.com

Optional:

• NGROK_DOMAIN — stable ngrok domain for consistent URLs
• WEBHOOK_PORT — local port (default: 4040)
• WEBHOOK_PATH — webhook path (default: /webhook)
• OPENCLAW_BIN — path to openclaw binary (default: openclaw)
• OPENCLAW_NOTIFY_CHANNEL — notification channel (default: whatsapp)
• OPENCLAW_NOTIFY_TARGET — phone number / target for notifications

Usage

Start the webhook listener

Run as a background process:

cd skills/ngrok-unofficial-webhook-skill
node scripts/webhook-server.js

The server prints its public URL to stderr:

NGROK_URL=https://xxxx.ngrok-free.app
Webhook endpoint: https://xxxx.ngrok-free.app/webhook

For long-running use, launch with nohup:

nohup node scripts/webhook-server.js >> /tmp/ngrok-webhook.log 2>&1 &

What happens when a webhook arrives

1. The server immediately responds 200 OK to the sender
2. It discovers installed skills that declare webhookEvents in their skill.json
3. Auto-routing (no user intervention needed):
   • If a matching skill has forwardPort → HTTP POST to the local service
   • If a matching skill has webhookCommands → runs the configured shell command
4. Manual routing (user decides):
   • If no auto-route is available, sends a WhatsApp notification with the payload and a numbered list of matching skills
   • User replies with their choice

Skill discovery

Skills opt into webhook handling by adding webhookEvents to their skill.json:

{
  "openclaw": {
    "webhookEvents": ["meeting.rtms_started", "meeting.rtms_stopped"],
    "forwardPort": 4048,
    "forwardPath": "/"
  }
}

For command-based auto-handling (no running service required):

{
  "openclaw": {
    "webhookEvents": ["recording.completed"],
    "webhookCommands": {
      "recording.completed": {
        "command": "python3 scripts/download.py {{meeting_id}}",
        "description": "Download cloud recording",
        "meetingIdPath": "payload.object.id"
      }
    }
  }
}

• command — shell command to run; {{meeting_id}} is replaced with the extracted value
• meetingIdPath — dot-separated path to extract the meeting ID from the webhook payload
• description — human-readable description for notifications

The ngrok skill scans all sibling skill folders for skill.json files with these fields.

Stdout output

The server also writes each webhook as a JSON line to stdout for process polling:

{
  "id": "uuid",
  "timestamp": "ISO-8601",
  "method": "POST",
  "path": "/webhook",
  "query": {},
  "body": {}
}

Health check

curl http://localhost:4040/health

Stop the listener

Kill the background process when done.

Integration with Zoom

Typical flow:

1. Start this webhook listener → get ngrok URL
2. Configure the ngrok URL in your Zoom Marketplace app's webhook settings
3. When RTMS starts, Zoom sends meeting.rtms_started → auto-forwarded to the RTMS Meeting Assistant
4. When RTMS stops, Zoom sends meeting.rtms_stopped → auto-forwarded, triggers cleanup

Ngrok Unofficial Webhook Skill

Start a public webhook endpoint via ngrok to receive incoming webhooks from any service. Auto-discovers installed skills that can handle specific webhook events and routes them accordingly.

Unofficial — This skill is not affiliated with or endorsed by ngrok.

Requires OpenClaw — This skill uses the OpenClaw CLI for notifications.

Features

• Public webhook URL — Instant ngrok tunnel with optional static domain
• Skill auto-discovery — Scans sibling skill folders for skill.json with webhookEvents
• Auto-forwarding — Routes matching events to skills with forwardPort (e.g. RTMS service)
• Auto-execution — Runs shell commands for matching events via webhookCommands config
• User notifications — Sends WhatsApp/Telegram notifications with event details and skill options
• Health check — Built-in /health endpoint

Quick Start

1. Install dependencies

cd skills/ngrok-unofficial-webhook-skill
npm install

2. Configure

Copy .env.example to .env and fill in:

NGROK_AUTHTOKEN=your_ngrok_auth_token
NGROK_DOMAIN=your-static-domain.ngrok-free.app
OPENCLAW_NOTIFY_TARGET=+1234567890

Get your auth token from https://dashboard.ngrok.com

3. Start

node scripts/webhook-server.js

The server prints its public URL:

NGROK_URL=https://your-domain.ngrok-free.app
Webhook endpoint: https://your-domain.ngrok-free.app/webhook

How It Works

Webhook arrives → Auto-routing

1. Server responds 200 OK immediately
2. Discovers installed skills that declare webhookEvents in their skill.json
3. Routes the event:
   • forwardPort — HTTP POST to a local service (e.g. RTMS assistant on port 4048)
   • webhookCommands — Runs a shell command with the meeting ID extracted from the payload
   • Neither — Notifies user with payload and skill options to choose from

Skill Discovery

Skills opt into webhook handling by declaring events in their skill.json:

{
  "openclaw": {
    "webhookEvents": ["meeting.rtms_started", "meeting.rtms_stopped"],
    "forwardPort": 4048,
    "forwardPath": "/"
  }
}

For command-based handling (no running service needed):

{
  "openclaw": {
    "webhookEvents": ["recording.completed"],
    "webhookCommands": {
      "recording.completed": {
        "command": "python3 scripts/download.py {{meeting_id}}",
        "description": "Download cloud recording",
        "meetingIdPath": "payload.object.id"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
NGROK_AUTHTOKEN	✅	—	ngrok auth token
NGROK_DOMAIN	—	random	Static ngrok domain for consistent URLs
WEBHOOK_PORT	—	4040	Local server port
WEBHOOK_PATH	—	/webhook	Webhook endpoint path
OPENCLAW_BIN	—	openclaw	Path to OpenClaw binary
OPENCLAW_NOTIFY_CHANNEL	—	whatsapp	Notification channel
OPENCLAW_NOTIFY_TARGET	—	—	Phone number / target for notifications

API Endpoints

# Health check
curl http://localhost:4040/health

# Webhooks are received at
POST http://localhost:4040/webhook

Integration with Zoom

Typical flow with Zoom RTMS:

1. Start this webhook listener → get ngrok URL
2. Set the ngrok URL as your Zoom Marketplace app's webhook endpoint
3. Zoom sends meeting.rtms_started → auto-forwarded to RTMS Meeting Assistant
4. Zoom sends meeting.rtms_stopped → auto-forwarded, triggers cleanup

Related Skills

• zoom-unofficial-community-skill — Zoom REST API CLI for meetings, recordings, and more
• zoom-meeting-assistance-rtms-unofficial-community — RTMS meeting capture and AI analysis

Bug Reports & Contributing

Found a bug? Please raise an issue at: 👉 https://github.com/tanchunsiong/ngrok-unofficial-webhook-skill/issues

Pull requests are also welcome!

License

MIT