Local Server Tunneling - Africa's Talking AI Integration Course

Overview

To receive webhooks from Africa’s Talking, your local development server must be accessible from the internet. Tunneling tools create a secure connection between a public URL and your local server, allowing external services to reach your endpoints.

Why Tunneling is Required

Africa’s Talking sends webhook notifications (SMS delivery reports, voice events, etc.) to your configured callback URLs. Since these services run on Africa’s Talking’s servers, they can’t reach localhost on your development machine. Tunneling solves this by:

Creating a public HTTPS URL that forwards to your local server
Providing secure encrypted connections
Allowing real-time testing of webhooks during development

For production deployments, you’ll deploy your application to a server with a public IP address or domain, eliminating the need for tunneling.

Tunneling Options

This guide covers three popular tunneling solutions:

ngrok - Feature-rich, reliable, with a free tier
Cloudflare Tunnel (cloudflared) - Free, no account required for basic use
localhost.run - Simple SSH-based tunneling, no installation needed

Option 1: ngrok (Recommended)

ngrok is the most popular and feature-rich tunneling solution, offering a generous free tier with persistent URLs on paid plans.

Installation

Download ngrok

Visit ngrok.com and download the version for your operating system.For macOS (using Homebrew):

brew install ngrok/ngrok/ngrok

For Linux:

curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

For Windows: Download the ZIP file from the ngrok website and extract it to a folder in your PATH.

Create an ngrok Account

Go to ngrok.com and sign up for a free account
After signing in, navigate to the dashboard
Copy your authentication token

Authenticate ngrok

Run the following command with your authentication token:

ngrok authtoken YOUR_NGROK_AUTH_TOKEN

This saves your token to ~/.ngrok2/ngrok.yml and authenticates all future sessions.

Add Token to .env File

Store your ngrok auth token in your .env file for reference:

NGROK_AUTHTOKEN=your-ngrok-auth-token-here

Starting ngrok

Once installed and authenticated, start ngrok to tunnel to your Flask application:

ngrok http 9000

Replace 9000 with the port number your Flask app is running on (check your .env file’s PORT variable).

Understanding ngrok Output

When ngrok starts, you’ll see output like this:

ngrok                                                                                                                                           
                                                                                                                                                
Build better APIs with ngrok. Early access: ngrok.com/early-access                                                                             
                                                                                                                                                
Session Status                online                                                                                                            
Account                       [email protected] (Plan: Free)                                                                              
Version                       3.5.0                                                                                                             
Region                        United States (us)                                                                                                
Latency                       23ms                                                                                                              
Web Interface                 http://127.0.0.1:4040                                                                                             
Forwarding                    https://abc123.ngrok.io -> http://localhost:9000                                                                  
                                                                                                                                                
Connections                   ttl     opn     rt1     rt5     p50     p90                                                                       
                              0       0       0.00    0.00    0.00    0.00

Important information:

Forwarding URL: https://abc123.ngrok.io - This is your public URL
Web Interface: http://127.0.0.1:4040 - ngrok’s local dashboard for monitoring requests

The ngrok web interface at http://127.0.0.1:4040 is incredibly useful for debugging. It shows all incoming requests, their headers, payloads, and your server’s responses in real-time.

Using Your ngrok URL

Your public URL will be in the format: https://abc123.ngrok.io To access your Flask endpoints through ngrok:

# Local access
http://localhost:9000/api/sms/

# Public access via ngrok
https://abc123.ngrok.io/api/sms/

ngrok Advanced Features

Custom Subdomain (Paid Plans)

ngrok http 9000 --subdomain=my-at-webhook

This creates a persistent URL: https://my-at-webhook.ngrok.io

Configuration File

Create ~/.ngrok2/ngrok.yml for persistent configuration:

version: "2"
authtoken: YOUR_NGROK_AUTH_TOKEN
tunnels:
  africastalking:
    proto: http
    addr: 9000
    subdomain: my-at-webhook  # Paid feature

Start the named tunnel:

ngrok start africastalking

Regional Endpoints

For better performance in Africa:

ngrok http 9000 --region eu

Available regions: us, eu, ap, au, sa, jp, in

Use the eu (Europe) region for better latency when working with Africa’s Talking, as it’s geographically closer to Africa.

Option 2: Cloudflare Tunnel

Cloudflare Tunnel (cloudflared) is a free alternative that doesn’t require an account for basic use.

Installation

Install cloudflared

For macOS (using Homebrew):

brew install cloudflared

For Linux (Debian/Ubuntu):

wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

For Windows: Download from Cloudflare’s release page

Start the Tunnel

Run cloudflared with the quick tunnel feature:

cloudflared tunnel --url http://localhost:9000

Replace 9000 with your Flask app’s port.

Understanding cloudflared Output

2024-01-15T10:30:45Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to...
2024-01-15T10:30:46Z INF Requesting new quick Tunnel on trycloudflare.com...
2024-01-15T10:30:47Z INF +--------------------------------------------------------------------------------------------+
2024-01-15T10:30:47Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable): |
2024-01-15T10:30:47Z INF |  https://abc-def-123.trycloudflare.com                                                     |
2024-01-15T10:30:47Z INF +--------------------------------------------------------------------------------------------+

Your public URL: https://abc-def-123.trycloudflare.com

Cloudflare quick tunnels generate random URLs each time. For persistent URLs, you need to create a Cloudflare account and configure a named tunnel.

Persistent Cloudflare Tunnel (With Account)

cloudflared tunnel login

This opens a browser for authentication.

Create a Named Tunnel

cloudflared tunnel create africastalking-dev

Configure the Tunnel

Create a configuration file at ~/.cloudflared/config.yml:

tunnel: africastalking-dev
credentials-file: /home/username/.cloudflared/TUNNEL-ID.json

ingress:
  - hostname: your-domain.com
    service: http://localhost:9000
  - service: http_status:404

Start the Tunnel

cloudflared tunnel run africastalking-dev

Option 3: localhost.run

localhost.run is the simplest option, using SSH tunneling with no installation required.

Usage

Simply run this SSH command:

ssh -R 80:localhost:9000 [email protected]

Explanation:

-R 80:localhost:9000 - Forward remote port 80 to local port 9000
[email protected] - Connect without SSH keys

Output

Connect to http://abc123.localhost.run or https://abc123.localhost.run

Your public URLs:

HTTP: http://abc123.localhost.run
HTTPS: https://abc123.localhost.run

localhost.run URLs change with each session and may have rate limits. It’s best for quick testing rather than extended development sessions.

Custom Subdomain

ssh -R my-tunnel:80:localhost:9000 [email protected]

This attempts to create: https://my-tunnel.localhost.run (availability not guaranteed)

Comparison of Tunneling Solutions

Feature	ngrok	Cloudflare Tunnel	localhost.run
Installation	Required	Required	Not required
Account Required	Yes (free tier)	No (for quick tunnels)	No
Persistent URLs	Paid plans only	With account	No
HTTPS	Yes (automatic)	Yes (automatic)	Yes (automatic)
Web Dashboard	Yes	Via Cloudflare account	No
Request Inspection	Yes	Via logs	No
Custom Domains	Paid plans	With account	Limited
Stability	Excellent	Excellent	Good
Best For	Development & debugging	Production-like setups	Quick tests

Recommendation: Use ngrok for development due to its excellent debugging features and web dashboard. For production-like setups, consider Cloudflare Tunnel.

Configuring Your Application

Testing Your Tunnel

After starting your tunnel, test that it works:

# Test with curl (replace with your tunnel URL)
curl https://abc123.ngrok.io/api/sms/

Expected response:

{
  "service": "sms",
  "status": "ready"
}

Using the Tunnel URL with Africa’s Talking

Once your tunnel is running, you’ll use the public URL to configure webhooks in Africa’s Talking dashboard. For example, if your ngrok URL is https://abc123.ngrok.io, your webhook URLs will be:

SMS Delivery Reports: https://abc123.ngrok.io/api/sms/delivery-reports
SMS Two-way: https://abc123.ngrok.io/api/sms/twoway
Voice Instructions: https://abc123.ngrok.io/api/voice/instruct
Voice Events: https://abc123.ngrok.io/api/voice/events
Airtime Validation: https://abc123.ngrok.io/api/airtime/validation
Airtime Status: https://abc123.ngrok.io/api/airtime/status

See the Webhook Configuration guide for detailed instructions.

Troubleshooting

Tunnel Not Starting

Problem: ngrok or cloudflared fails to start. Solutions:

Verify you’ve authenticated (ngrok only)
Check that the port isn’t already in use
Ensure your Flask app is running before starting the tunnel
Check firewall settings

502 Bad Gateway Errors

Problem: Accessing the tunnel URL returns a 502 error. Solutions:

Verify your Flask application is running
Check that you’re tunneling to the correct port
Ensure the Flask app is binding to 0.0.0.0, not just 127.0.0.1

Webhooks Not Received

Problem: Africa’s Talking webhooks aren’t reaching your application. Solutions:

Verify the webhook URLs in Africa’s Talking dashboard are correct
Check ngrok’s web interface (http://127.0.0.1:4040) to see if requests are arriving
Ensure your routes match the configured webhook paths exactly
Check for HTTPS (Africa’s Talking requires HTTPS for webhooks)

Tunnel URL Changes

Problem: The tunnel URL changes every time you restart. Solutions:

ngrok: Upgrade to a paid plan for persistent URLs
Cloudflare: Set up a named tunnel with an account
Update webhook URLs in Africa’s Talking dashboard after each restart

During active development, keep your tunnel running continuously to avoid having to update webhook URLs repeatedly.

Rate Limits or Throttling

Problem: Getting rate limit errors or slow responses. Solutions:

ngrok free tier: Limited to 40 requests/minute
Upgrade to a paid plan for higher limits
Use Cloudflare Tunnel as an alternative

Security Considerations

Important Security Practices:

Never expose sensitive development databases through tunnels
Use environment-specific credentials (development vs. production)
Monitor tunnel access logs for suspicious activity
Close tunnels when not actively developing
Don’t share tunnel URLs publicly

Request Authentication

Consider adding authentication to your webhook endpoints:

from flask import request, abort
import os

def verify_africastalking_request():
    # Add authentication logic here
    # For example, checking IP addresses or signatures
    pass

IP Whitelisting

Africa’s Talking provides IP ranges for their webhook servers. You can restrict access to only these IPs in production.

Next Steps

Now that your local server is accessible from the internet:

Configure webhook URLs in the Africa’s Talking dashboard
Test your endpoints to ensure webhooks are received correctly
Learn about environment setup for managing secrets

Get Started

Core Concepts

API Services

AI Integration

Guides

​Overview

​Why Tunneling is Required

​Tunneling Options

​Option 1: ngrok (Recommended)

​Installation

​Starting ngrok

​Understanding ngrok Output

​Using Your ngrok URL

​ngrok Advanced Features

​Custom Subdomain (Paid Plans)

​Configuration File

​Regional Endpoints

​Option 2: Cloudflare Tunnel

​Installation

​Understanding cloudflared Output

​Persistent Cloudflare Tunnel (With Account)

​Option 3: localhost.run

​Usage

​Output

​Custom Subdomain

​Comparison of Tunneling Solutions

​Configuring Your Application

​Testing Your Tunnel

​Using the Tunnel URL with Africa’s Talking

​Troubleshooting

​Tunnel Not Starting

​502 Bad Gateway Errors

​Webhooks Not Received

​Tunnel URL Changes

​Rate Limits or Throttling

​Security Considerations

​Request Authentication

​IP Whitelisting

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Overview

Why Tunneling is Required

Tunneling Options

Option 1: ngrok (Recommended)

Installation

Starting ngrok

Understanding ngrok Output

Using Your ngrok URL

ngrok Advanced Features

Custom Subdomain (Paid Plans)

Configuration File

Regional Endpoints

Option 2: Cloudflare Tunnel

Installation

Understanding cloudflared Output

Persistent Cloudflare Tunnel (With Account)

Option 3: localhost.run

Usage

Output

Custom Subdomain

Comparison of Tunneling Solutions

Configuring Your Application

Testing Your Tunnel

Using the Tunnel URL with Africa’s Talking

Troubleshooting

Tunnel Not Starting

502 Bad Gateway Errors

Webhooks Not Received

Tunnel URL Changes

Rate Limits or Throttling

Security Considerations

Request Authentication

IP Whitelisting

Next Steps

Additional Resources