AutoWebhook

AutoWebhook is a library for Node.js and Bun that automatically creates and manages tunnels using services like ngrok and localhost.run. It provides stable public URLs for your local server, which is ideal for developing and testing webhooks.

The library runs your chosen tunnel provider in the background, monitors its status, automatically restarts it in case of failures, and provides a simple API to manage one or multiple tunnels simultaneously.

Why AutoWebhook?

When developing services that use webhooks, you need a public HTTPS URL. Tunneling services are excellent for this, but often require manual startup and management.

AutoWebhook automates this entire process:

• Automatic Start: Runs tunnel providers alongside your application.
• Multi-Provider: Supports ngrok and localhost.run out of the box.
• Multi-Tunnel: Run and manage multiple tunnels at the same time.
• Monitoring and Restart: A built-in health checker monitors each tunnel and automatically restarts it on failure.
• Simplicity: Eliminates the need for manual steps and extra scripts.

Core Features

• Automatic Tunnel Management: Start, stop, and restart in the background.
• Multi-Provider Support: Use ngrok, localhost.run, and other future providers.
• Multi-Tunnel Management: Run multiple tunnels simultaneously for high availability or A/B testing.
• Health Check: Optional component to monitor the status of each tunnel.
• Reliability: Automatic restart on connection loss or failures.
• Flexible Configuration: Configure multiple tunnels, each with its own provider, port, and provider-specific settings.
• Event-driven Architecture: Get real-time notifications for each tunnel's status.
• TypeScript Support: Fully typed for robust development.

Installation

npm install autowebhook
# or with bun
bun add autowebhook
# or with yarn
yarn add autowebhook

Quick Start

Here's how you can get a public URL for your local server in just a few lines:

// index.ts
import { AutoWebhook } from 'autowebhook';

// 1. Configure a tunnel
const webhook = new AutoWebhook({
  tunnels: [{ name: 'my-app', provider: 'ngrok', port: 3000 }]
});

// 2. Start the tunnel(s)
const [url] = await webhook.start(); // .start() returns an array of URLs

console.log(`App running at: ${url}`);

// Your local server logic that will listen on port 3000
// ...

Requirements

• Node.js: >= 18.0.0
• Bun: >= 1.0.0 (optional)
• TypeScript: >= 5.0.0 (optional, but recommended)

For ngrok tunnels, you may need to install ngrok separately or provide an auth token for advanced features.

Documentation

For detailed configuration, API methods, and events, see the API Reference.

For more complex use cases, including how to set up a Telegram bot or manage multiple tunnels, see the Usage Examples.

Package Contents

This package is published as compiled JavaScript with TypeScript definitions:

• ESM: dist/index.js (ES modules)
• CommonJS: dist/index.cjs (CommonJS modules)
• Types: dist/index.d.ts (TypeScript definitions)

The package supports both import and require syntax:

// ESM
import { AutoWebhook } from 'autowebhook';

// CommonJS
const { AutoWebhook } = require('autowebhook');

Development

# Clone the repository
gh repo clone rozeraf/autowebhook

# Install dependencies
bun install

# Run tests
bun test

# Build the package
bun run build

# Run linting
bun run lint

Changelog

All changes are documented in the CHANGELOG.md file.

Troubleshooting

Common Issues

1. Tunnel fails to start

   • Check if the port is already in use
   • Verify your ngrok authtoken if using premium features
   • Ensure you have necessary permissions to execute the tunnel binary

2. Health check failures

   • Verify your network connection
   • Check if your local server is responding
   • Adjust health check timeout if network latency is high

3. "Port already in use" errors

   // Make sure to stop existing tunnels before starting new ones
   await existingWebhook.stop();
   await new AutoWebhook().start();

4. TypeScript import issues

   // If you see type errors, make sure your tsconfig.json includes:
   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "esModuleInterop": true
     }
   }

Getting Help

• Open an issue on GitHub
• Check the API Reference for detailed documentation
• Review the Examples for common usage patterns

License

This project is distributed under the GPL-3.0-only license. See the LICENSE file for more information.