Webhooks — Universal Event Entry

Imagine your front door only opened when you personally turned the key—no package deliveries, no guests while you’re away. That’s how most software works until you add webhooks: a universal doorbell that lets any outside service ring in and trigger your agent to act.

What’s a Webhook, Really?

A webhook is just an HTTP POST request sent to a URL when something happens. GitHub says “a PR was opened,” Stripe says “a payment failed,” JIRA says “a ticket moved.” Your Hermes Agent listens on that URL, validates the request is genuine, turns the event into a prompt, and then your agent decides what to do—comment on the PR, send a Telegram message, or just log the result.

Quick Start in Three Steps

1. Enable the gateway — run hermes gateway setup and follow the prompts, or add these lines to ~/.hermes/.env:

   WEBHOOK_ENABLED=true
   WEBHOOK_PORT=8644
   WEBHOOK_SECRET=your-global-secret

2. Define a route — either in config.yaml under platforms.webhook.extra.routes, or dynamically with hermes webhook subscribe.
3. Point your service at http://your-server:8644/webhooks/<route-name>.

Verify it’s alive with:

curl http://localhost:8644/health

You should see {"status": "ok", "platform": "webhook"}.

Anatomy of a Route

Each route is a named entry in your config. The most important property is secret—it’s required and used for HMAC signature validation. Never skip it in production. (The "INSECURE_NO_AUTH" value is for local testing only.)

You can also add a prompt template to shape how the payload becomes an agent instruction. For example, {pull_request.title} pulls just the PR title into the prompt. If you omit it, the full JSON payload is dumped in—useful but noisy.

Filters Keep You Sane

Use filters to ignore events you don’t care about. For instance, only act when action == "opened" and pull_request.base.ref == "main". This saves agent runs and tokens.

A Word of Caution

The docs say it plainly: authenticated does not mean trusted. Even with a valid HMAC signature, the payload content comes from an external party. Never put payload fields directly into shell commands or SQL queries. Treat them as untrusted input.

Final Tip

Start with one route and one event type. Get that working end-to-end, then expand. And always set a per-route secret—it’s the difference between a doorbell and an open gate.