Gareth Wilson
Hookdeck for Hermes Agent: Reliable webhook-triggered agent runs
Hermes is Nous Research's self-hosted AI agent. It runs on your own machine, keeps persistent memory across sessions, creates its own reusable skills, and talks to you over Telegram, Discord, Slack, WhatsApp, Signal, or your terminal.
When Hermes Agent shipped webhook-triggered sessions, it answered one of the most-requested features in the project's history. It let external events start agent runs instead of relying on cron. The community loved it, wired up their agents, but a few issues started to appear.
Agents can reply twice to the same event. Bursty sources can exceed the 30-requests-per-minute route limit. Signature verification proved easy to get wrong or skip. And if you restart, you quickly find that that in-flight events don't wait around.
None of this is a criticism of Hermes. These are the same failure modes every team hits when webhooks meet production, and we've spent years watching developers rediscover them. What makes agents different is the cost of each failure. A webhook handler that runs twice wastes a few milliseconds of compute. An agent run that fires twice burns real money and might comment on your PR twice or email your customer twice. A dropped event means the agent never did its job, and nothing tells you.
So we built hermes-hookdeck, an official Hookdeck plugin for Hermes Agent. It puts Event Gateway in front of your agent, a durable, verified queue, so a webhook can trigger a run without all the ways that can go wrong.
What it adds to Hermes
The plugin can replace or run alongside Hermes own webhook ingestion, adding Hookdeck's Event Gateway plus a local run ledger that tracks what Hookdeck can't see:
| Native Hermes | With the plugin | |
|---|---|---|
| Signature verification | A handful of providers | 140+ provider schemes, verified at the edge |
| Gateway offline | Events lost | Events held server-side, drained on resume |
| Traffic bursts | 30/min, excess dropped | Queued; overflow gets a 503 with Retry-After |
| Duplicates | In-memory 1h cache, gone on restart | Hookdeck dedup plus a restart-safe SQLite ledger |
| Failed runs | Lost after the 202 | Redelivered by Hookdeck |
| Mid-run crashes | Silently lost | Recovered from the ledger at boot |
That last row is a big one. The built-in platform acknowledges a webhook with a 202 and runs the agent afterwards. If the run fails, the provider believes it delivered and never retries. So the plugin keeps a ledger of every delivery and its outcome in SQLite at ~/.hermes/hookdeck/state.db, so a failed or interrupted run can be redelivered, even after a crash or a restart.
Your agent can triage its own failures
Operators get the commands you'd expect: hermes hookdeck status for queue depth and failures, pause and resume to hold events server-side during a deploy, retry for individual events, and doctor to check the whole setup.
More interesting is what the agent gets. The plugin exposes tools like hookdeck_list_failed_events, hookdeck_get_event_body, hookdeck_retry_event, and hookdeck_bulk_retry, along with a bundled triage-webhook-failures skill. Instead of retrying everything and hoping, the agent groups failures by error code, retries what a retry will actually fix, and reports the rest. Your agent becomes its own on-call engineer for the queue it consumes from.
No public URL required
The default mode uses the Hookdeck CLI, which holds an outbound connection and forwards events to a local listener. Your Hermes gateway can sit behind NAT on a laptop or a homelab box, with no ngrok and no exposed port. If you do run on a public URL, push mode unlocks delivery rate limits, issue triggers, and alerting on top.
Getting started
Install Hookdeck CLI, then set your two keys from your Hookdeck project settings, and install the plugin:
brew install hookdeck # or: npm install -g hookdeck-cli
export HOOKDECK_EG_API_KEY=...
export HOOKDECK_EG_WEBHOOK_SECRET=...
hermes plugins install hookdeck/hermes-hookdeck
hermes plugins enable hookdeck
hermes hookdeck setup my-route
hermes hookdeck doctor will confirm everything is wired up. A free Hookdeck account covers development and small production workloads.
The plugin source is on GitHub. If you hit a rough edge, open an issue there or find us in the Hookdeck Slack — we're keen to hear how the Hermes community puts it to work.