Files
szzhoujiarui bb4e1497e1 fix(webhook): refuse a delivery target the gateway cannot dispatch
`hermes webhook subscribe --deliver telegram/all` was stored as-is, and at
delivery time the gateway found no platform called "telegram/all", logged a
warning nobody saw and dropped the response. The command looked like it worked
and nothing was ever delivered.

- `subscribe` validates `--deliver` against the same `_is_known_platform`
  check runtime dispatch uses (plus log/github_comment, plus plugin platforms
  after discovery) and exits 1 with the supported syntax.
- `list` marks an already-persisted unknown target `(INVALID)` with the fix
  command.
- The gateway skips such a dynamic route on load with a warning that names the
  fix, instead of accepting events it can never deliver.

Ported from #84184 by @szzhoujiarui onto the reshaped current webhook module.

Fixes #84171
2026-11-14 03:49:07 -08:00

75 lines
4.2 KiB
Python

"""``hermes webhook`` subcommand parser."""
from __future__ import annotations
from typing import Callable
def build_webhook_parser(subparsers, *, cmd_webhook: Callable) -> None:
"""Attach the ``webhook`` subcommand to ``subparsers``."""
webhook_parser = subparsers.add_parser(
"webhook", help="Manage dynamic webhook subscriptions",
description="Create, list, and remove webhook subscriptions for event-driven agent activation",
)
webhook_subparsers = webhook_parser.add_subparsers(dest="webhook_action")
wh_sub = webhook_subparsers.add_parser(
"subscribe", aliases=["add"], help="Create a webhook subscription")
wh_sub.add_argument("name", help="Route name (used in URL: /webhooks/<name>)")
wh_sub.add_argument(
"--prompt", default="", help="Prompt template with {dot.notation} payload refs")
wh_sub.add_argument("--events", default="", help="Comma-separated event types to accept")
wh_sub.add_argument("--description", default="", help="What this subscription does")
wh_sub.add_argument("--skills", default="", help="Comma-separated skill names to load")
wh_sub.add_argument(
"--deliver", default="log",
help="Delivery target name: log, telegram, discord, slack, etc. Pass the chat ID with --deliver-chat-id.")
wh_sub.add_argument(
"--deliver-chat-id", default="", help="Target chat ID for cross-platform delivery")
wh_sub.add_argument("--secret", default="", help="HMAC secret (auto-generated if omitted)")
wh_sub.add_argument(
"--signature", choices=("generic", "github", "gitlab", "linear"), default=None,
help="Signature scheme this route accepts; every other header family is rejected. generic "
"(default for new routes) = X-Webhook-Signature-V2 + X-Webhook-Timestamp or Standard Webhooks/Svix; "
"github = X-Hub-Signature-256; gitlab = X-Gitlab-Token or a GitLab signing token; "
"linear = Linear-Signature. Kept on update when omitted.")
wh_sub.add_argument(
"--route-profile", dest="route_profile", default=None, metavar="PROFILE",
help="Bind the route to a multiplexed profile: only POSTs to /p/PROFILE/webhooks/<name> "
"are accepted and the agent runs as that profile (default: default; kept on update). "
"Changing an existing route's profile rotates its HMAC secret unless a different --secret is supplied. "
"Distinct from the global -p/--profile, which picks the gateway whose subscriptions "
"file is written.")
wh_sub.add_argument(
"--deliver-only", action="store_true",
help="Skip the agent — deliver the rendered prompt directly as the "
"message. Zero LLM cost. Requires --deliver to be a real target "
"(not 'log').")
wh_sub.add_argument(
"--mirror-to-session", action="store_true",
help="Also write each delivered message into the target chat's session, so replying to it "
"in that chat has context. Only for sources whose content you trust in your conversation.")
wh_sub.add_argument(
"--script", default="",
help="Filter/transform script under ~/.hermes/scripts/. The route "
"payload is passed as JSON on stdin; empty stdout, [SILENT], or a "
"nonzero exit code ignores the webhook.")
wh_sub.add_argument(
"--cron-job", default="",
help="Fire an existing cron job (by ID or name) when this route receives an event, instead of "
"starting a fresh agent run. The rendered --prompt template is passed to the job as transient "
"per-run context; the job's own prompt, skills, and delivery settings apply. Mutually exclusive "
"with --deliver-only.")
webhook_subparsers.add_parser("list", aliases=["ls"], help="List all dynamic subscriptions")
wh_rm = webhook_subparsers.add_parser("remove", aliases=["rm"], help="Remove a subscription")
wh_rm.add_argument("name", help="Subscription name to remove")
wh_test = webhook_subparsers.add_parser("test", help="Send a test POST to a webhook route")
wh_test.add_argument("name", help="Subscription name to test")
wh_test.add_argument(
"--payload", default="", help="JSON payload to send (default: test payload)")
webhook_parser.set_defaults(func=cmd_webhook)