v3: retire the VERIFY_TOKEN signing-key fallback

[ord669]

Signature verification now keys only on WEBHOOK_HMAC_SECRET — the || VERIFY_TOKEN fallback is removed (breaking, hence v3). The fallback was a compat bridge for .env files written before the verify-token/HMAC split; the CLI has exported WEBHOOK_HMAC_SECRET from both sandbox env and channels env since 0.12.x, so a fresh hookmyapp sandbox env --write .env (or channels env) is the migration.

VERIFY_TOKEN keeps its one remaining role: the body echoed on the one-time webhook verification GET (channels flow). .env.example, README, AGENTS.md, the boot warning, and the tests are updated to match; 43/43 tests pass.

Tracked as AIT-126 in Linear.

Summary by CodeRabbit

• New Features
  • Webhook signatures are now verified exclusively with WEBHOOK_HMAC_SECRET.
  • Added clearer channel filtering and Instagram sender labels in /chat.
  • Improved /logs summaries for inbound Instagram webhooks.
• Bug Fixes
  • Corrected handling of invalid webhook signatures and malformed request bodies.
  • Instagram sender IDs are now displayed without an unwanted + prefix.
• Documentation
  • Updated setup, environment variable, troubleshooting, and signature verification guidance.
• Release
  • Updated the application to version 3.0.0.

[coderabbitai]

📝 Walkthrough

Walkthrough

Webhook signature verification now relies only on WEBHOOK_HMAC_SECRET. Tests, environment guidance, troubleshooting documentation, package versioning, and the v3 changelog are updated accordingly.

Changes

Webhook signing v3

Layer / File(s)	Summary
HMAC-only runtime verification src/index.js, test/routes.test.js	createApp removes the VERIFY_TOKEN signing fallback, warns only when WEBHOOK_HMAC_SECRET is unset, and tests the updated webhook signature outcomes.
Environment and verification guidance .env.example, AGENTS.md, README.md	Environment provisioning, signature verification, sandbox keys, and troubleshooting guidance now describe WEBHOOK_HMAC_SECRET and the remaining verify-GET role of VERIFY_TOKEN.
Version and release documentation package.json, CHANGELOG.md	The package version is set to 3.0.0, with changelog entries documenting the updated verification behavior and release changes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: removing the VERIFY_TOKEN signing-key fallback in v3.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ait-126-retire-verify-token-signing-fallback

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

CHANGELOG.md (1)

27-38: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Changelog "Changed" entry contradicts the "Breaking" section above it.

Line 29-30 says signature verification "now keys on WEBHOOK_HMAC_SECRET, falling back to VERIFY_TOKEN when unset (a compat bridge...)", but the Breaking section (lines 7-9) states the opposite: verification "no longer falls back to VERIFY_TOKEN" as of this same 3.0.0 release. This reads like leftover text from an earlier (v2) changelog entry that was never updated to reflect the v3 fallback removal, and it's inconsistent with the actual behavior in src/index.js and the AGENTS.md/README.md updates in this PR.

📝 Proposed fix

 ### Changed

-- Signature verification now keys on `WEBHOOK_HMAC_SECRET`, falling back to
-  `VERIFY_TOKEN` when unset (a compat bridge: sandbox sessions and channels
-  created before the verify-token/HMAC split export the signing secret under
-  `VERIFY_TOKEN`). `VERIFY_TOKEN` itself is only the webhook verify-GET
-  handshake response. A missing secret now logs a boot warning instead of
-  exiting.
+- `VERIFY_TOKEN` itself is only the webhook verify-GET handshake response. A
+  missing `WEBHOOK_HMAC_SECRET` logs a boot warning instead of exiting.
 - The Instagram provider reads the sandbox or real-channel base URL with
   `INSTAGRAM_ACCOUNT_ID`, so the kit runs against a connected Instagram channel
   without a code change.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` around lines 27 - 38, Update the “Changed” entry in
CHANGELOG.md to remove the claim that signature verification falls back to
VERIFY_TOKEN, and describe the v3.0.0 behavior consistently with the Breaking
section and implementation: use WEBHOOK_HMAC_SECRET only, with a missing secret
producing a boot warning rather than exiting.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@CHANGELOG.md`:
- Around line 27-38: Update the “Changed” entry in CHANGELOG.md to remove the
claim that signature verification falls back to VERIFY_TOKEN, and describe the
v3.0.0 behavior consistently with the Breaking section and implementation: use
WEBHOOK_HMAC_SECRET only, with a missing secret producing a boot warning rather
than exiting.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6bb5222-72ff-4a81-8e30-f007bc212b29

📥 Commits

Reviewing files that changed from the base of the PR and between d5ac4af and 727dcbc.

📒 Files selected for processing (7)

• .env.example
• AGENTS.md
• CHANGELOG.md
• README.md
• package.json
• src/index.js
• test/routes.test.js