Live webhook

active · reviewed 2026-06-23

Live webhook testing runs the real @wats/service with the fetch-backed Graph transport against Meta. Meta needs a public HTTPS callback — a localhost URL will not work. This page covers the tunnel, the live serve wrapper, and the webhook onboarding checklist.

For config scaffolding, offline diagnostics, and dry-run serve, see CLI onboarding.

Start a public HTTPS tunnel

Meta calls your webhook over public HTTPS. Run a secure HTTPS tunnel first:

ngrok http 8787

ngrok is one option; any HTTPS tunnel that fronts 127.0.0.1:8787 works. Note the https://<your-tunnel-host> URL it prints.

Run the live serve wrapper

WATS_LIVE_ENABLE=1 WATS_YES_LIVE=1 \
  wats serve --config wats.config.yaml --live --yes-live --env-file .env.local

• --live declares live intent.
• --yes-live acknowledges that service routes can call Graph when you hit them.
• --env-file .env.local is required; WATS does not read .env.local implicitly. Keep the env file local and gitignored.

This is for local live testing behind a secure HTTPS tunnel, not production hosting.

Live serve resolves only the four secret keys below; WABA/phone ids and live-gate markers can remain in the file. Values are placeholder only — do not commit real secrets:

WATS_ACCESS_TOKEN=***
WATS_VERIFY_TOKEN=***
WATS_APP_SECRET=***
WATS_SERVICE_TOKEN=***

Output stays status-only: no profile names, config paths, env names, tokens, app secrets, verify tokens, service bearer values, or Graph responses.

Verify the service is up before pointing Meta at it:

curl -fsS http://127.0.0.1:8787/healthz
curl -fsS http://127.0.0.1:8787/readyz

Webhook onboarding checklist

Use wats onboarding once you know the public HTTPS URL for your tunnel or deployed WATS service:

wats onboarding --public-url https://example.test/wats
wats onboarding --public-url https://example.test --webhook-path /webhooks/whatsapp

The command prints the webhook callback address to paste into Meta App Dashboard > WhatsApp > Configuration, plus two locally generated values:

• WATS_VERIFY_TOKEN — use as the Meta webhook verify token; store it in your local env/secret manager.
• WATS_SERVICE_TOKEN — use as the bearer token for protected WATS service routes.

You still copy these from Meta yourself: WATS_ACCESS_TOKEN, WATS_APP_SECRET, WATS_WABA_ID, WATS_PHONE_NUMBER_ID. The command prints generated values to stdout only; it does not write files, read .env.local, resolve existing secrets, or call Meta Graph APIs.

Credential safety

The general CLI safety contract lives in CLI onboarding. Live-specific rules:

• --env-file must be a relative local filename; absolute paths, traversal, duplicate flags, and token-looking values fail closed.
• Keep .env.local local and gitignored. Do not commit access tokens, app secrets, webhook verify tokens, service bearer tokens, or WABA/phone-number ids from real accounts.
• No live Meta calls without explicit opt-in (--live --yes-live); no secret values printed.

Related

• CLI onboarding — init, setup wizard, doctor, dry-run serve.
• CLI reference — wats serve, wats onboarding, wats messages.
• Service reference — the standalone service the wrapper runs.