Webhook Subscriptions - Setup Guide¶

Source: nousresearch/hermes-agent (80 installs) Category: Automation / Integration License: MIT · Platforms: Linux, macOS Dependencies: Hermes Agent, Hermes Gateway with webhook platform enabled

Create dynamic webhook subscriptions so external services can trigger Hermes agent runs by POSTing events to a URL. GitHub pushes, Stripe payment events, CI/CD pipeline completions, IoT sensor alerts - any service that can send an HTTP POST becomes a trigger for Hermes to take action.

What It Does¶

Capability	How
Event-driven agent runs	External service POSTs → Hermes processes event
HMAC signature verification	Prevents spoofed requests - only trusted sources trigger
Payload-to-context injection	Webhook body becomes agent context
Per-subscription filtering	Route different events to different profiles/skills
Dynamic subscription management	Create, list, delete subscriptions from Hermes

Architecture¶

┌──────────────┐   POST /webhook/abc123    ┌──────────────────┐
│  GitHub      │──────────────────────────▶│  Hermes Gateway  │
│  (push event)│   HMAC-SHA256 signature   │  :8742            │
└──────────────┘                           └────────┬─────────┘
                                                     │
┌──────────────┐   POST /webhook/def456    ┌────────▼─────────┐
│  Stripe      │──────────────────────────▶│  Agent Dispatch  │
│  (payment)   │   HMAC-SHA256 signature   │  (profile + ctx) │
└──────────────┘                           └──────────────────┘

Installation¶

Via skills.sh (Recommended)¶

npx skills add https://github.com/nousresearch/hermes-agent --skill webhook-subscriptions

Direct from Hermes Agent Repo¶

git clone --depth 1 https://github.com/nousresearch/hermes-agent.git /tmp/hermes-agent
cp -r /tmp/hermes-agent/skills/automation/webhook-subscriptions ~/.hermes/skills/

Setup¶

Step 1: Enable the webhook platform¶

hermes gateway setup

Follow the prompts to: - Enable webhooks - Set the port (default: 8742) - Set a global HMAC secret (used to verify incoming signatures)

Verify it's running:

hermes webhook list

If it returns a list (even empty), the platform is active.

Step 2: Make gateway reachable (if external services)¶

For services like GitHub or Stripe to reach your local Hermes:

# Option A: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:8742

# Option B: ngrok
ngrok http 8742

# Option C: Direct (if on a public server)
# Ensure firewall allows port 8742

Step 3: Create a subscription¶

> Load webhook-subscriptions skill
> Create a webhook for GitHub push events on repo corpusiq/api
> Route to profile: corpusiq, skill: deploy-on-push

Basic Usage¶

Creating subscriptions¶

> Subscribe to GitHub push events for corpusiq/api
> Create a Stripe webhook for payment_intent.succeeded events
> Watch my CI pipeline - trigger on build complete

Listing and managing¶

> List my webhook subscriptions
> Delete webhook subscription abc123
> Show the webhook URL for my GitHub subscription

Testing¶

> Test webhook abc123 with a sample GitHub payload

Security Model¶

Layer	Protection
HMAC signatures	Every incoming request must carry a valid HMAC-SHA256 signature matching the global secret
Per-subscription secrets	Optionally override global secret per subscription for provider-specific keys
Payload validation	Malformed JSON rejected before agent sees it
Rate limiting	Gateway-level rate limiting prevents abuse

Provider-Specific Setup¶

GitHub¶

Repo → Settings → Webhooks → Add webhook
Payload URL: https://your-domain/webhook/<subscription-id>
Content type: application/json
Secret: Your HMAC secret
Events: Select "Just the push event" or choose specific events

Stripe¶

Stripe Dashboard → Developers → Webhooks → Add endpoint
Endpoint URL: https://your-domain/webhook/<subscription-id>
Events to send: Select specific events (e.g., payment_intent.succeeded)
Signing secret: Your HMAC secret

Tips¶

One subscription per event source: Don't multiplex - create separate subscriptions for GitHub, Stripe, CI
Profile routing: Route production events to your ops profile, dev events to your dev profile
Test with sample payloads: Use the test command before wiring up live services
Monitor in gateway logs: hermes gateway logs shows incoming webhook activity

Troubleshooting¶

Problem	Likely Cause	Fix
"Webhook platform not enabled"	Gateway not configured	Run `hermes gateway setup`
401 on incoming requests	HMAC mismatch	Verify secret matches between Hermes and sender
Gateway not reachable	Port not exposed	Use Cloudflare Tunnel or ngrok
Agent not triggering	Wrong profile/skill routing	Check subscription config with `hermes webhook list`

← Skills Catalog | nousresearch/hermes-agent on skills.sh

Powered by CorpusIQ

Integration with CorpusIQ¶

CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.

This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.

See what CorpusIQ connects