Webhooks
What it is
External events that trigger bounded Hermes work.
In plain terms
Picture an apartment building where each business gets its own labeled mail slot instead of sharing one front desk. A webhook is that slot: an outside service — GitHub, a form tool, a monitoring alert — drops a signed, sealed note the moment something happens, and Hermes’s front desk checks the courier’s badge before anything reaches the mailbox and triggers work.
Why it matters
An external event landing on Hermes’s API surface is what actually triggers event-driven work — a webhook — and it’s deliberately bounded, scoped tightly enough that an unexpected or malformed payload doesn’t cascade into unrelated agent behavior. That boundedness is the operative design choice, not an afterthought: a webhook-triggered job is meant to do one specific thing, not open an unconstrained session. Webhooks show up as their own route group on the dashboard API, alongside cron and messaging.
How it works
Each route is defined statically in config.yaml or dynamically in ~/.hermes/webhook_subscriptions.json, with an event filter, required HMAC secret, optional prompt template, and delivery target (gateway/platforms/webhook.py). Incoming events use POST /webhooks/{route_name}; multi-profile gateways also expose POST /p/{profile}/webhooks/{route_name}. The adapter enforces a body-size cap, verifies GitHub, GitLab, or generic HMAC signatures against the raw body before JSON parsing, filters event types, and suppresses duplicate delivery IDs. There is no generic /events/outage route unless an operator explicitly creates a route whose name and gateway path match that configuration.
A concrete example
You configure a route named pr-review with events set to pull_request, an HMAC secret, a prompt template referencing {pull_request.title} and {pull_request.user.login}, and deliver set to github_comment with the repo and PR number. When a teammate opens a pull request, GitHub sends a signed POST. Hermes verifies the signature, confirms pull_request is an allowed event, renders the template, runs the agent against that one PR, and posts its reply back as a comment on that exact pull request using the gh CLI — no polling, no separate script watching the repo.
How it connects
This note belongs to the Automation family. Its closest neighboring concepts are: No-Model Jobs, Event-Driven Agents, Agent Runtime, Personal OS.
Source evidence
route:GET:/api/webhooks— Explicit Source Map scope boundary: The web server route is outside the approved Core scope.
Workflows
- No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
Related articles
- Ten Hermes Workflows That Turn a Chatbot into a 24/7 Assistant
- Ten Underused Hermes Features That Reveal Its Real Power