Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Telegram webhook settings in the config UI did not clearly explain webhook URL/secret semantics and defaults; startup logging only showed the public webhook URL particularly port 8787 was not disclosed as the default in the web UI help text and was also not logged on startup of the gateway. Fixed main regression in port 0 not being allowed - per request from @obviyus
• Why it matters: Operators need clear guidance to configure webhook mode correctly and to troubleshoot local listener bind details quickly. Issue Telegram webhook returns 405 Method Not Allowed #4417 shows that folks are confused about the port that the Telegram Webhook runs on because neither the config UI nor the startup logs tell them the actual port that the webhook is listening on.
• What changed: Added Telegram webhook field help/default text in config schema (webhookUrl, webhookSecret, webhookPath, webhookHost, webhookPort) and added a startup log line for the local listener URL (http://host:port/path), while keeping the existing public URL log.
• What did NOT change (scope boundary): No change to webhook startup validation behavior; missing channels.telegram.webhookSecret with channels.telegram.webhookUrl is still rejected at config validation/startup.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Telegram webhook returns 405 Method Not Allowed #4417
• Related [BUG]: fix telegram webhook should wait for abort signal instead of returning #20309

User-visible / Behavior Changes

• Telegram channel config screen now shows inline help/default guidance for webhook fields.
• Startup logs now include local listener URL in addition to public webhook URL.
• Public webhook URL log remains unchanged.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS (local dev machine)
• Runtime/container: Node 22 / local gateway run
• Model/provider: N/A
• Integration/channel (if any): Telegram
• Relevant config (redacted): channels.telegram.webhookUrl, channels.telegram.webhookSecret, channels.telegram.webhookHost, channels.telegram.webhookPort, channels.telegram.webhookPath

Steps

1. Configure Telegram webhook settings in Channels config UI and open Telegram section.
2. Start gateway with webhook settings configured.
3. Observe startup logs for Telegram channel.
4. Observe inline documentation for the Telegram webhook settings

Expected

• Startup logs include both local listener URL and expected public webhook URL.
• Telegram webhook settings show clear inline help/default guidance.

Actual

• Current version has little to no inline documentation
• Current version does not print local listening endpoint for telegram webhook

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Sanitized startup log snippet

19:05:12 [telegram] [default] starting provider (@example_bot)
19:05:12 [telegram] autoSelectFamily=true (default-node22)
19:05:12 [telegram] dnsResultOrder=ipv4first (default-node22)
19:05:13 [telegram] webhook local listener on http://127.0.0.1:8787/telegram-webhook
19:05:13 [telegram] webhook advertised to telegram on https://oc-tg.example.com/telegram-webhook

Log snippet when webhoookPort: 0

13:32:53 [telegram] webhook local listener on http://127.0.0.1:56969/telegram-webhook

Screenshot - Web UI After

Screenshot - Startup Logs

Added log line:

19:05:13 [telegram] webhook local listener on http://127.0.0.1:8787/telegram-webhook

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Opened browser and confirmed help text is present on Channels config screen for Telegram.
  • Started up and confirmed the webhook local listener line is printed when configured.
  • Confirmed that Telegram webhook is registered correctly and can pickup messages from the Telegram.
• Edge cases checked:
  • Config validation still rejects channels.telegram.webhookUrl without channels.telegram.webhookSecret on startup.
• What you did not verify:
  • Nothing?

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert this PR commit.
• Files/config to restore: N/A (just revert)
• Known bad symptoms reviewers should watch for: None

Risks and Mitigations

• Risk: Help text can drift if defaults change later.
• Mitigation: Keep default values in help text aligned with webhook implementation defaults during future changes.

Greptile Summary

Enhanced Telegram webhook configuration guidance by adding inline help text for all webhook-related fields (webhookUrl, webhookSecret, webhookPath, webhookHost, webhookPort) in the config schema. Added startup logging to display the local listener URL alongside the existing public webhook URL log, improving troubleshooting visibility for operators.

• Config schema improvements clearly document webhook field semantics and defaults (port 8787, host 127.0.0.1, path /telegram-webhook)
• New startup log line shows local listener binding details (http://host:port/path)
• Test coverage updated to verify both log lines are emitted
• No changes to webhook validation behavior or security model

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Documentation-focused changes that add inline help text and improve logging visibility. No logic changes to webhook behavior, validation, or security. Test coverage properly validates the new logging. The only minor suggestion is clarifying HTTPS requirement wording in the help text.
• No files require special attention

_{Last reviewed commit: 337770c}