🔗 Webhook Setup Guide

📊 Webhook Status

Local Server: Checking...
Webhook URL: http://localhost:8000/webhook
Public URL (ngrok):

📋 Setup Steps

Step 1: Install ngrok

  1. Download ngrok from: https://ngrok.com/download
  2. Extract the zip file
  3. Move ngrok.exe to a folder in your PATH (or run from current directory)

Step 2: Start ngrok

Open a NEW command prompt (keep your server running) and run: 

ngrok http 8000

You'll see output like: 

Forwarding   https://xxxx-xx-xx-xx-xx.ngrok.io -> http://localhost:8000

Copy the HTTPS URL (the one that starts with https://xxxx.ngrok.io)

Step 3: Configure Meta Business Manager

  1. Go to Meta Business Manager
  2. Select your WhatsApp Business Account
  3. Click "WhatsApp Manager" → "Configuration"
  4. Scroll to "Webhook" section
  5. Click "Edit" or "Configure Webhook"

Step 4: Enter Webhook Details

Callback URL:

https://YOUR-NGROK-URL.ngrok.io/webhook

Example: https://a1b2-123-45-67-89.ngrok.io/webhook

Verify Token:

my_secret_token_123

(This is from your .env file: WEBHOOK_VERIFY_TOKEN)

Click "Verify and Save"

Step 5: Subscribe to Webhook Fields

After verification, subscribe to these fields:

  • messages ✅ (Required)
  • message_echoes (optional)
  • message_status (optional)

Click "Subscribe" or "Done"

🧪 Test Your Webhook

Testing Steps:

  1. Send a WhatsApp message to your business number from your phone
  2. Watch your server terminal - you should see: 
    📨 WEBHOOK RECEIVED
📞 From: 923xxxxxxxxx
👤 Name: Your Name
💬 Message: Hello
✅ Message saved to database
  3. Open Chat Inbox page - the message should appear
  4. Reply from Chat Inbox - you should receive it on WhatsApp

💡 Webhook Console

Waiting for webhook events... Send a message to your WhatsApp Business number to test.

🔧 Troubleshooting

❌ Webhook verification failed

  • Check if ngrok is running
  • Verify your server is running on port 8000
  • Ensure WEBHOOK_VERIFY_TOKEN in .env matches what you entered
  • Use HTTPS URL from ngrok (not HTTP)

❌ Not receiving messages

  • Check if "messages" field is subscribed
  • Verify ngrok is still running (free tier restarts with new URL)
  • Check server terminal for webhook logs
  • Try re-verifying webhook in Meta Business Manager

💡 ngrok Free Tier Limitations

  • URL changes every time you restart ngrok
  • You'll need to update webhook URL in Meta each time
  • For production, use a permanent hosting service