​

Testing Webhooks Locally with Ngrok

​

What is Ngrok?

​

Setting Up Ngrok

​

Step 1: Install Ngrok

1. Visit ngrok.com and sign up for a free account
2. Download and install Ngrok for your operating system
3. Authenticate your Ngrok installation with your auth token:

ngrok config add-authtoken YOUR_AUTH_TOKEN

​

Step 2: Start Your Local Server

​

Step 3: Connect Ngrok to Your Local Port

ngrok http 3000

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.3.1
Region                        United States (us)
Latency                       24ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://a1b2-203-0-113-42.ngrok-free.app -> http://localhost:3000

​

Configuring A1Base with Your Ngrok URL

1. Log in to the A1Base dashboard at https://www.a1base.com/dashboard/phone-numbers.
2. Navigate to the “Phone Numbers” section and locate the phone number you wish to configure (e.g., 14155356190).
3. In the “Webhook URL” column for that phone number, enter your Ngrok HTTPS URL combined with your endpoint path (e.g., https://a1b2-203-0-113-42.ngrok-free.app/whatsapp/incoming).
4. Click the “Save” button next to the webhook URL field to apply the changes.
   Refer to the A1Base dashboard screenshot for a visual guide on configuring webhook URLs: Phone Numbers Dashboard.

​

Development vs. Production Phone Numbers

​

Why Use Separate Phone Numbers?

1. Isolated Testing: Test new features without affecting your production users
2. Prevent Webhook Conflicts: Avoid routing production messages to your development environment
3. Easier Debugging: Clearly distinguish between development and production traffic
4. Safer Experimentation: Experiment with new features risk-free

​

Setting Up Development and Production Numbers

1. Purchase Two Phone Numbers: In your A1Base dashboard, purchase two separate phone numbers
2. Label Your Numbers: Clearly label one as “Development” and one as “Production”
3. Configure Different Webhooks:
   • Development number: Point to your Ngrok URL
   • Production number: Point to your production server URL
4. Use Environment Variables: In your code, use environment variables to determine which phone number to use:

// Example of using different phone numbers based on environment
const phoneNumber = process.env.NODE_ENV === 'production'
  ? process.env.A1BASE_PRODUCTION_PHONE
  : process.env.A1BASE_DEVELOPMENT_PHONE;

// Use the appropriate phone number for outgoing messages
a1base.sendMessage({
  to: recipientNumber,
  from: phoneNumber,
  message: "Hello from A1Base!"
});

​

Monitoring Webhook Traffic

• All incoming webhook requests
• Request and response headers
• Request and response bodies
• Timing information

​

Best Practices for Local Testing

1. Keep Ngrok Running: Maintain your Ngrok session while testing to avoid URL changes
2. Log All Webhook Data: Implement comprehensive logging in your development environment
3. Simulate Different Scenarios: Test various message types and edge cases
4. Verify Webhook Signatures: Even in development, validate webhook signatures if available
5. Test Error Handling: Ensure your application handles webhook failures gracefully

​

Limitations and Considerations

• Free Tier Restrictions: Ngrok’s free tier has limitations on connections and features
• URL Changes: Free Ngrok URLs change each time you restart Ngrok
• Latency: There may be slight additional latency when using Ngrok
• Security: Be cautious about sensitive data passing through your development environment