· 4 min · TextMeFlow Team

Test WhatsApp API Webhooks Locally with ngrok

You want to build a new WhatsApp integration — a bot, a CRM link, a notification flow — but your server runs on localhost. TextMeFlow can't send anything there: webhooks are outgoing POST requests from our servers to a publicly reachable URL. Until your code is on a real server, you need a tunnel. This article shows how to do that with ngrok, without accidentally leaving a half-finished endpoint in production.

Why test locally in the first place

You could wait until your endpoint is deployed to see whether the payload is right, but that's slow: every change needs a new deploy to find out whether your JSON parsing, your signature check and your business logic work together. Testing locally with a real, live webhook — instead of a hand-crafted test payload — catches errors you'd otherwise only see in production: unexpected headers, the exact shape of from_name in group messages, or a media message with a file field you hadn't anticipated.

Step 1: start ngrok

Install ngrok (brew install ngrok or download it from their site) and start a tunnel to the port your local server runs on:

ngrok http 3000

Ngrok gives you a public URL like https://a1b2c3d4.ngrok-free.app that forwards to http://localhost:3000. On the free plan, that URL changes on every restart — keep that in mind if you repeat the next step several times.

Step 2: configure the webhook temporarily

Go to /admin/webhook and set the ngrok URL as your endpoint, for example https://a1b2c3d4.ngrok-free.app/webhooks/whatsapp. As soon as you save, you'll see the webhook secret — copy it right away, because it's masked afterwards. Send yourself a test WhatsApp message to your linked number and check whether the request arrives on your local server.

Treat that ngrok configuration as throwaway work: as soon as you're done testing, point the endpoint back to your real production URL. A forgotten ngrok tunnel that no longer exists after a laptop restart is the fastest way to silently lose all incoming messages.

Step 3: verify the signature, even locally

It's tempting to skip the HMAC check "because it's only local testing" — but then you're not testing what actually happens in production. Read the raw body before any JSON middleware gets to it, and check X-TextMeFlow-Signature right away:

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.TMF_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-textmeflow-signature'] || ''))) {
    return res.sendStatus(401);
  }

  const payload = JSON.parse(req.body);
  console.log(payload);
  res.sendStatus(200);
});

app.listen(3000);

More details on the headers, retry logic and the safest way to compare the signature are in the article on webhook signatures.

Step 4: use the ngrok inspector to replay

Ngrok's local web interface at http://127.0.0.1:4040 logs every incoming request, including headers and body. That's handy for two things without having to send a new WhatsApp message each time:

  • Looking at the exact payload TextMeFlow sent, so you can write your parsing code against it.
  • Replaying the same request ("Replay") after deploying a bug fix to your local server, without sending another message.

One caveat: a replay through the ngrok inspector reuses the same X-TextMeFlow-Event-Id. If your idempotency logic is based on that field — which we recommend — your own code will rightly ignore the replay. That's not a bug, that's your dedup logic working.

Common mistakes

The webhook stays "pending" or keeps failing: check that your endpoint returns a 2xx within 10 seconds. Run heavy processing (updating a CRM, calling an external API) after that response, not before — otherwise your local server looks like it timed out and you get needless retries with a backoff of 1m, 5m, 30m, 2h and 6h.

A second classic mistake: the ngrok URL changes on every restart (free plan), but the webhook secret stays the same as long as you don't recreate the endpoint. If you update the URL in /admin/webhook but your local .env still has the old secret, you'll get 401s everywhere — rarely "an attack", usually just an out-of-sync secret.

Ready to go live

Once your endpoint signs, parses and responds correctly within 10 seconds locally, all you need to do is replace the URL in /admin/webhook with your production address. All TextMeFlow infrastructure runs in the EU (Paris), so your test and production traffic stays within the EU as well. No account yet? The free plan gives you 50 messages per month, forever — enough to test this entire flow end to end. Start for free.

Want to send WhatsApp messages via API yourself?

Free forever up to 50 messages/month. Scan a QR and send your first message within 5 minutes.

Free forever