feat(webhook): hermes webhook CLI + skill for event-driven subscriptions (#3578)
Adds 'hermes webhook' CLI subcommand and a skill — zero new model tools. CLI commands (require webhook platform to be enabled): hermes webhook subscribe <name> [--events, --prompt, --deliver, ...] hermes webhook list hermes webhook remove <name> hermes webhook test <name> All commands gate on webhook platform being enabled in config. If not configured, prints setup instructions (gateway setup wizard, manual config.yaml, or env vars). The agent uses these via terminal tool, guided by the webhook-subscriptions skill which documents setup, common patterns (GitHub, Stripe, CI/CD, monitoring), prompt template syntax, security, and troubleshooting. Adapter enhancement: webhook.py hot-reloads dynamic subscriptions from ~/.hermes/webhook_subscriptions.json on each incoming request (mtime-gated). Static config.yaml routes always take precedence. Docs: updated webhooks.md with Dynamic Subscriptions section, added hermes webhook to cli-commands.md reference. No new model tools. No toolset changes. 24 new tests for CLI CRUD, persistence, enabled-gate, and adapter dynamic route loading.
This commit is contained in:
Teknium
@@ -39,6 +39,7 @@ hermes [global-options] <command> [subcommand/options]
|
||||
| `hermes login` / `logout` | Authenticate with OAuth-backed providers. |
|
||||
| `hermes status` | Show agent, auth, and platform status. |
|
||||
| `hermes cron` | Inspect and tick the cron scheduler. |
|
||||
| `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. |
|
||||
| `hermes doctor` | Diagnose config and dependency issues. |
|
||||
| `hermes config` | Show, edit, migrate, and query configuration files. |
|
||||
| `hermes pairing` | Approve or revoke messaging pairing codes. |
|
||||
@@ -214,6 +215,39 @@ hermes cron <list|create|edit|pause|resume|run|remove|status|tick>
|
||||
| `status` | Check whether the cron scheduler is running. |
|
||||
| `tick` | Run due jobs once and exit. |
|
||||
|
||||
## `hermes webhook`
|
||||
|
||||
```bash
|
||||
hermes webhook <subscribe|list|remove|test>
|
||||
```
|
||||
|
||||
Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `subscribe` / `add` | Create a webhook route. Returns the URL and HMAC secret to configure on your service. |
|
||||
| `list` / `ls` | Show all agent-created subscriptions. |
|
||||
| `remove` / `rm` | Delete a dynamic subscription. Static routes from config.yaml are not affected. |
|
||||
| `test` | Send a test POST to verify a subscription is working. |
|
||||
|
||||
### `hermes webhook subscribe`
|
||||
|
||||
```bash
|
||||
hermes webhook subscribe <name> [options]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--prompt` | Prompt template with `{dot.notation}` payload references. |
|
||||
| `--events` | Comma-separated event types to accept (e.g. `issues,pull_request`). Empty = all. |
|
||||
| `--description` | Human-readable description. |
|
||||
| `--skills` | Comma-separated skill names to load for the agent run. |
|
||||
| `--deliver` | Delivery target: `log` (default), `telegram`, `discord`, `slack`, `github_comment`. |
|
||||
| `--deliver-chat-id` | Target chat/channel ID for cross-platform delivery. |
|
||||
| `--secret` | Custom HMAC secret. Auto-generated if omitted. |
|
||||
|
||||
Subscriptions persist to `~/.hermes/webhook_subscriptions.json` and are hot-reloaded by the webhook adapter without a gateway restart.
|
||||
|
||||
## `hermes doctor`
|
||||
|
||||
```bash
|
||||
|
||||
@@ -48,6 +48,14 @@ Creative content generation — ASCII art, hand-drawn style diagrams, and visual
|
||||
| `ascii-video` | "Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid… | `creative/ascii-video` |
|
||||
| `excalidraw` | Create hand-drawn style diagrams using Excalidraw JSON format. Generate .excalidraw files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. | `creative/excalidraw` |
|
||||
|
||||
## devops
|
||||
|
||||
DevOps and infrastructure automation skills.
|
||||
|
||||
| Skill | Description | Path |
|
||||
|-------|-------------|------|
|
||||
| `webhook-subscriptions` | Create and manage webhook subscriptions for event-driven agent activation. External services (GitHub, Stripe, CI/CD, IoT) POST events to trigger agent runs. Requires webhook platform to be enabled. | `devops/webhook-subscriptions` |
|
||||
|
||||
## dogfood
|
||||
|
||||
| Skill | Description | Path |
|
||||
|
||||
@@ -15,7 +15,7 @@ The agent processes the event and can respond by posting comments on PRs, sendin
|
||||
## Quick Start
|
||||
|
||||
1. Enable via `hermes gateway setup` or environment variables
|
||||
2. Define webhook routes in `config.yaml`
|
||||
2. Define routes in `config.yaml` **or** create them dynamically with `hermes webhook subscribe`
|
||||
3. Point your service at `http://your-server:8644/webhooks/<route-name>`
|
||||
|
||||
---
|
||||
@@ -205,6 +205,56 @@ For cross-platform delivery (telegram, discord, slack, signal, sms), the target
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Subscriptions (CLI) {#dynamic-subscriptions}
|
||||
|
||||
In addition to static routes in `config.yaml`, you can create webhook subscriptions dynamically using the `hermes webhook` CLI command. This is especially useful when the agent itself needs to set up event-driven triggers.
|
||||
|
||||
### Create a subscription
|
||||
|
||||
```bash
|
||||
hermes webhook subscribe github-issues \
|
||||
--events "issues" \
|
||||
--prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
|
||||
--deliver telegram \
|
||||
--deliver-chat-id "-100123456789" \
|
||||
--description "Triage new GitHub issues"
|
||||
```
|
||||
|
||||
This returns the webhook URL and an auto-generated HMAC secret. Configure your service to POST to that URL.
|
||||
|
||||
### List subscriptions
|
||||
|
||||
```bash
|
||||
hermes webhook list
|
||||
```
|
||||
|
||||
### Remove a subscription
|
||||
|
||||
```bash
|
||||
hermes webhook remove github-issues
|
||||
```
|
||||
|
||||
### Test a subscription
|
||||
|
||||
```bash
|
||||
hermes webhook test github-issues
|
||||
hermes webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'
|
||||
```
|
||||
|
||||
### How dynamic subscriptions work
|
||||
|
||||
- Subscriptions are stored in `~/.hermes/webhook_subscriptions.json`
|
||||
- The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
|
||||
- Static routes from `config.yaml` always take precedence over dynamic ones with the same name
|
||||
- Dynamic subscriptions use the same route format and capabilities as static routes (events, prompt templates, skills, delivery)
|
||||
- No gateway restart required — subscribe and it's immediately live
|
||||
|
||||
### Agent-driven subscriptions
|
||||
|
||||
The agent can create subscriptions via the terminal tool when guided by the `webhook-subscriptions` skill. Ask the agent to "set up a webhook for GitHub issues" and it will run the appropriate `hermes webhook subscribe` command.
|
||||
|
||||
---
|
||||
|
||||
## Security {#security}
|
||||
|
||||
The webhook adapter includes multiple layers of security:
|
||||
|
||||
Reference in New Issue
Block a user