Documentation Menu

Testing WhatsApp Webhooks (Meta Graph API)

The "hub.challenge" Nightmare

Meta's webhook verification process is notoriously difficult to test locally. When you configure a webhook in the Meta App Dashboard, Meta instantly fires a synchronous GET request containing a hub.challenge parameter. Your endpoint MUST echo back this exact integer in plain text. If your local tunnel isn't running properly, or if SSL termination drops the request, Meta will permanently reject your endpoint.

The Hookmetry CLI provides a secure, persistent HTTPS tunnel that seamlessly handles Meta's SSL requirements, allowing you to debug the handshake directly in your local terminal.

Step 1: Start the Secure Tunnel

Forward traffic to your local WhatsApp handler (e.g., a Fastify or Express route):

hookmetry listen --forward localhost:8080/api/whatsapp

Step 2: Echo the Challenge

Ensure your local code handles the GET request correctly:

app.get('/api/whatsapp', (req, res) => {\n  if (req.query['hub.verify_token'] === 'YOUR_CUSTOM_TOKEN') {\n    return res.status(200).send(req.query['hub.challenge']);\n  }\n  res.sendStatus(403);\n});

Step 3: Verify in Meta Dashboard

  1. Go to Meta App Dashboard > WhatsApp > Configuration.
  2. Paste the persistent Hookmetry Forwarding URL into the Callback URL field.
  3. Enter your custom Verify Token.
  4. Click Verify and Save.

Because Hookmetry's edge network handles the TLS certificates flawlessly, Meta will connect instantly. You can now subscribe to messages fields and receive live WhatsApp messages in your local IDE.

Was this page helpful?

Your feedback helps us improve the docs.