webhook.py 3.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667
  1. """``hermes webhook`` subcommand parser."""
  2. from __future__ import annotations
  3. from typing import Callable
  4. def build_webhook_parser(subparsers, *, cmd_webhook: Callable) -> None:
  5. """Attach the ``webhook`` subcommand to ``subparsers``."""
  6. webhook_parser = subparsers.add_parser(
  7. "webhook", help="Manage dynamic webhook subscriptions",
  8. description="Create, list, and remove webhook subscriptions for event-driven agent activation",
  9. )
  10. webhook_subparsers = webhook_parser.add_subparsers(dest="webhook_action")
  11. wh_sub = webhook_subparsers.add_parser(
  12. "subscribe", aliases=["add"], help="Create a webhook subscription")
  13. wh_sub.add_argument("name", help="Route name (used in URL: /webhooks/<name>)")
  14. wh_sub.add_argument(
  15. "--prompt", default="", help="Prompt template with {dot.notation} payload refs")
  16. wh_sub.add_argument("--events", default="", help="Comma-separated event types to accept")
  17. wh_sub.add_argument("--description", default="", help="What this subscription does")
  18. wh_sub.add_argument("--skills", default="", help="Comma-separated skill names to load")
  19. wh_sub.add_argument(
  20. "--deliver", default="log", help="Delivery target: log, telegram, discord, slack, etc.")
  21. wh_sub.add_argument(
  22. "--deliver-chat-id", default="", help="Target chat ID for cross-platform delivery")
  23. wh_sub.add_argument("--secret", default="", help="HMAC secret (auto-generated if omitted)")
  24. wh_sub.add_argument(
  25. "--route-profile", dest="route_profile", default=None, metavar="PROFILE",
  26. help="Bind the route to a multiplexed profile: only POSTs to /p/PROFILE/webhooks/<name> "
  27. "are accepted and the agent runs as that profile (default: default; kept on update). "
  28. "Changing an existing route's profile rotates its HMAC secret unless a different --secret is supplied. "
  29. "Distinct from the global -p/--profile, which picks the gateway whose subscriptions "
  30. "file is written.")
  31. wh_sub.add_argument(
  32. "--deliver-only", action="store_true",
  33. help="Skip the agent — deliver the rendered prompt directly as the "
  34. "message. Zero LLM cost. Requires --deliver to be a real target "
  35. "(not 'log').")
  36. wh_sub.add_argument(
  37. "--mirror-to-session", action="store_true",
  38. help="Also write each delivered message into the target chat's session, so replying to it "
  39. "in that chat has context. Only for sources whose content you trust in your conversation.")
  40. wh_sub.add_argument(
  41. "--script", default="",
  42. help="Filter/transform script under ~/.hermes/scripts/. The route "
  43. "payload is passed as JSON on stdin; empty stdout, [SILENT], or a "
  44. "nonzero exit code ignores the webhook.")
  45. wh_sub.add_argument(
  46. "--cron-job", default="",
  47. help="Fire an existing cron job (by ID or name) when this route receives an event, instead of "
  48. "starting a fresh agent run. The rendered --prompt template is passed to the job as transient "
  49. "per-run context; the job's own prompt, skills, and delivery settings apply. Mutually exclusive "
  50. "with --deliver-only.")
  51. webhook_subparsers.add_parser("list", aliases=["ls"], help="List all dynamic subscriptions")
  52. wh_rm = webhook_subparsers.add_parser("remove", aliases=["rm"], help="Remove a subscription")
  53. wh_rm.add_argument("name", help="Subscription name to remove")
  54. wh_test = webhook_subparsers.add_parser("test", help="Send a test POST to a webhook route")
  55. wh_test.add_argument("name", help="Subscription name to test")
  56. wh_test.add_argument(
  57. "--payload", default="", help="JSON payload to send (default: test payload)")
  58. webhook_parser.set_defaults(func=cmd_webhook)