Webhook Receiver - Receive External Callbacks via Aitun Tunnel#

When to Use#

Use this skill when:

• You need to receive a webhook from a third-party service (GitHub, Stripe, Slack, etc.)
• You are implementing an OAuth flow and need a callback URL
• You want to capture form submissions or API callbacks from external systems
• You need to test webhook integrations locally without deploying to a server
• You are building an event-driven workflow that reacts to external HTTP notifications

Do NOT use this skill when:

• You only need to make outgoing HTTP requests (no tunnel needed)
• The callback can be handled by a long-polling or WebSocket connection you initiate
• You already have a public server endpoint to receive the callbacks

Instructions#

Step 1: Install aitun#

bash

pip install aitun

Or install via one-line script (Linux/macOS):

bash

curl -fsSL https://aitun.cc/install.sh | bash

Windows (PowerShell):

powershell

irm https://aitun.cc/install.ps1 | iex

Or verify it is already installed:

bash

which aitun

Step 2: Start a local webhook handler#

Create a simple HTTP server that processes incoming webhook requests. For example, a Python handler:

python

# webhook_handler.py
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

class WebhookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        body = self.rfile.read(content_length)
        try:
            data = json.loads(body)
        except Exception:
            data = body.decode()

        print(f"Received webhook at {self.path}")
        print(f"Headers: {dict(self.headers)}")
        print(f"Body: {data}")

        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps({"status": "ok"}).encode())

    def do_GET(self):
        # Useful for verification endpoints
        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps({"status": "alive"}).encode())

if __name__ == '__main__':
    server = HTTPServer(('0.0.0.0', 8080), WebhookHandler)
    print("Webhook handler listening on port 8080")
    server.serve_forever()

Start the handler:

bash

python3 webhook_handler.py &
HANDLER_PID=$!
sleep 1

Step 3: Create a tunnel#

Expose the local handler to the internet:

bash

aitun -p 8080 &
AITUN_PID=$!
sleep 3

The output will contain the public URL, e.g.:

• https://aitun.cc/abc123

Step 4: Register the webhook URL#

Use the tunnel URL as the webhook/callback endpoint with the third-party service:

• For GitHub webhooks: Set payload URL to https://aitun.cc/abc123/webhook
• For OAuth callbacks: Set redirect URI to https://aitun.cc/abc123/callback
• For payment notifications: Set notification URL to https://aitun.cc/abc123/notify
• For generic webhooks: Set the endpoint to https://aitun.cc/abc123/ + your path

Tell the user:

text

Your webhook is now live at: https://aitun.cc/abc123

Register this URL as the callback endpoint in your third-party service.
This tunnel is active and will expire in 24 hours.

Step 5: Process incoming webhooks#

When a request arrives, your handler will log it. You can then:

• Parse the payload and extract relevant data
• Trigger follow-up actions based on the event type
• Store the data for later processing
• Send a response back to the caller

Step 6: Clean up#

When done, stop the servers:

bash

kill $AITUN_PID 2>/dev/null
kill $HANDLER_PID 2>/dev/null

CLI Reference#

The aitun command (installed via pip install aitun, or alternatively curl -fsSL https://aitun.cc/install.sh | bash / irm https://aitun.cc/install.ps1 | iex on Windows) accepts these flags:

FlagDescription-p PORTLocal HTTP service port (optional; omit for TCP-only mode with --tcp-ports)-k TOKENAuth token for registered subdomain (omit for free tunnel)--host HOSTLocal service address (default: localhost)--tcp-ports PORTSTCP forwarding ports, comma-separated (e.g., 22,3306; requires -k). Use without -p for TCP-only mode--p2pEnable P2P direct connection (default: enabled)--no-p2pDisable P2P, force server relay mode--daemonRun as background daemon--stopStop running daemon

Notes#

• Free tunnels use proxy address mode (path-based URL like aitun.cc/abc123), NOT subdomains
• Free tunnels expire after 24 hours, auto-renewed on restart
• For a permanent webhook endpoint, register at https://aitun.cc to get a custom subdomain
• Webhook handlers should always return a 200 response quickly to avoid timeouts from the sender
• Some services (e.g., GitHub) send a verification challenge on setup — your handler should respond to GET requests
• All traffic is encrypted end-to-end
• For debugging, log the full request headers and body before processing