Webhook Routing

Where to find each webhook URL, what each one does, and how to verify delivery end-to-end.

Sandbox URL

hookmyapp sandbox listen opens a Cloudflare tunnel from a HookMyApp-managed public hostname to http://localhost:3000/webhook by default. The tunnel URL is auto-provisioned. You don't configure it.

View the current sandbox URL with hookmyapp sandbox status. It prints the public hostname, your pinned phone, the session expiry, and the activation code.

Production URL

For a connected WABA, you set the production webhook URL with hookmyapp webhook set. HookMyApp writes it to Meta's override_callback_uri field via the Graph API. That override takes precedence over any URL you configure in the Meta App Dashboard's Webhooks card.

# Set the production URL
hookmyapp webhook set 1276334778010256 \
  --url https://api.acme.com/whatsapp/webhook \
  --verify-token $(openssl rand -hex 32)
 
# View the current override URL and verification state
hookmyapp webhook show 1276334778010256

Verify Delivery End-to-end

  1. Check the current override. hookmyapp webhook show <waba-id> prints the URL and its verified status. If the status is not verified, your server failed the GET challenge.
  2. Check WABA health. hookmyapp health <waba-id> shows phone status, webhook state, and quality rating. Anything not healthy means Meta cannot deliver.
  3. Send yourself a test message. From another phone, send a message to your WABA's number. Watch your server logs for the inbound POST and a 200 response.
  4. If signature fails: refresh env. A signature-mismatch 401 means your local VERIFY_TOKEN is stale. Re-run hookmyapp sandbox env --write .env (sandbox) or hookmyapp env <waba-id> (production) and restart your server.

When Things Break

  • Webhook verify GET returns 404: your server is not handling GET /webhook. Add the verification route that echoes VERIFY_TOKEN.
  • Signature mismatch on POST: your .env is stale. Re-pull env values and restart.
  • No delivery at all: run hookmyapp health <waba-id>. If it's unhealthy, delivery is blocked at Meta. If channels disable was run, Meta disabled your WABA and you need to re-enable.
  • Sandbox tunnel drops: hookmyapp sandbox listen exited. Re-run it.

Next Steps