Webhook routing

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

Sandbox tunnel

hookmyapp sandbox listen opens a secure 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.

If you are using the starter kit, it serves per-channel routes. Select the route with --path:

hookmyapp sandbox listen --port 3000 --path /webhook/whatsapp
hookmyapp sandbox listen --port 3000 --path /webhook/instagram

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

Tunnel to your own channel (local dev)

hookmyapp channels listen <channel> opens the same kind of tunnel for a connected WhatsApp number or Instagram account. Meta is pointed at the tunnel hostname while the CLI runs; on exit, the tunnel is reclaimed and Meta's webhook URL reverts to whatever was set before.

Use this to develop locally against your real WhatsApp number or Instagram account without standing up a public HTTPS endpoint first. Select the starter kit's per-channel route with --path:

hookmyapp channels listen ch_xxxxxxxx --path /webhook/whatsapp
hookmyapp channels listen ch_xxxxxxxx --path /webhook/instagram
# or omit the channel arg for the interactive picker:
hookmyapp channels listen

If you set a webhook URL (next section) while a channels listen tunnel is active, the CLI exits with CHANNEL_TUNNEL_RECLAIMED. The two paths are mutually exclusive per channel.

Your own webhook URL (deployed)

When your receiver is deployed behind a stable public URL, set it with hookmyapp channels 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 your own webhook URL (use the route for the channel's type:
# /webhook/whatsapp for a WhatsApp channel, /webhook/instagram for Instagram)
hookmyapp channels webhook set ch_xxxxxxxx \
  --url https://api.acme.com/webhook/whatsapp \
  --verify-token $(openssl rand -hex 32)
 
# View the current override URL and verification state
hookmyapp channels webhook show ch_xxxxxxxx
 
# Remove the override URL (reverts to the CLI tunnel or dashboard config)
hookmyapp channels webhook clear ch_xxxxxxxx

Verify delivery end-to-end

  1. Check the current override. hookmyapp channels webhook show <channel> prints the URL and its verified status. If the status is not verified, your server failed the GET challenge.
  2. Check channel health. hookmyapp channels health <channel> shows phone status, webhook state, and quality rating. Anything not healthy means Meta cannot deliver.
  3. Send yourself a test message. From another account, message your WhatsApp number or Instagram account. 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 channels env <channel> (your own channel) and restart your server.

When things break

  • Webhook verify GET returns 404: your server is not handling GET /webhook/whatsapp (or /webhook/instagram). 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 channels health <channel>. If it's unhealthy, delivery is blocked at Meta. If channels disable was run, Meta disabled your WhatsApp number and you need to re-enable.
  • Sandbox tunnel drops: hookmyapp sandbox listen exited. Re-run it.
  • Tunnel reclaimed: hookmyapp channels listen exited with CHANNEL_TUNNEL_RECLAIMED. Something else set a webhook URL on the channel (CLI elsewhere, dashboard, or the tunnel row was reaped). Re-run channels listen if you still want the tunnel.

Next steps